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Using This Book 

Purpose 

SAS/C Development System Library Reference describes the content and 
use of each of the libraries available to the SAS/C and C+ + programmer 
under AmigaDOS. Some of these libraries are provided by Commodore, 
and some are provided by the SAS/C Development System. 

“Using This Book” describes how you can best use this book. It 
describes the book’s intended audience, the audience’s prerequisite 
knowledge, the book’s organization and its conventions, and additional 
documentation that is available to you. 


Audience 

The information in this book is written for experienced C and/or C+ + 
programmers. This book assumes you have a working knowledge of C 
and/or C+ + and AmigaDOS. For a list of publications you can use to 
learn C, C++, or AmigaDOS, refer to the section “Additional 
Documentation” at the end of “Using This Book.” 


How to Use This Book 

This section gives an overview of the book’s organization and content. 
The book’s chapters are described, followed by a section on how to use 
each chapter. 

Organization SAS/C Development System Library Reference is organized into eight 
chapters: 

Chapter 1, “What Libraries Can I Access” 

describes the two major types of libraries and lists all of the libraries 
you can access from your SAS/C programs. 

Chapter 2, “Using the Commodore Libraries” 

describes how to access the shared libraries provided by Commodore. 
Chapter 3, “Using the SAS/C Libraries” 

describes each of the libraries provided by the SAS/C Development 
System. It also explains which compiler options enable you to access 
these libraries. 

Chapter 4, “Using the System Header Files to Access Libraries” 

describes how to use header files and built-in functions to speed up 
the compilation and reduce the size of your program. 



Using This Book 


xii 


Chapter 5, “Advanced Library Techniques” 

describes how to create your own shared libraries, linkable libraries, 
and devices and how to create and use your own # pragma 
statements. 

Chapter 6, “Predefined Data Name Reference” 

describes each of the data names provided by the SAS/C Development 
System. 

Chapter 7, “C Library Reference” 

describes each of the C library functions provided by the SAS/C 
Development System. 

Chapter 8, “C+ + Library Reference” 

describes each of the C+ + library functions provided by the SAS/C 
Development System. 

What You Should The following table points you to specific chapters in this book for 
Read information on particular topics. For other references, refer to 

“Additional Documentation” later in this section. 


For information on 

You should read 

major types of available libraries 

Chapter 1 

accessing libraries 

Chapters 2 and 3 

reducing the amount of time required to compile or 
the amount of disk space required to store your 
program 

Chapter 4 

creating your own libraries or devices 

Chapter 5 

specific C library functions or data names 
specific C+ + classes Chapter 8 

Chapters 6 and 7 


Conventions 

This section covers the typographical and syntax conventions used in this 
book. 
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Typographical 

Conventions 


Syntax 

Conventions 


The SAS/C books for AmigaDOS use special fonts to depict specific types 
of information. These typographical conventions are as follows: 


roman 

monospace 


oblique 


italic 


is the basic type style used for most text, 
is used to show example statements or programs. 
Monospace is used also for items specific to the 
C and C+ + languages, such as the names of functions, 
header files, and keywords. To distinguish between C and 
C+ + function names, the names of C + + functions are 
followed by parentheses, as in setf ( ). 
is used for argument, variable, or parameter values when 
they are shown as displayed by the SAS/C Development 
System. For example, a compiler message may contain a 
character string from your program, 
is used for terms that are defined and for arguments or 
variables whose values are supplied by the user. For 
example, you should enter an appropriate filename when 
you see filename. 


This book uses the following conventions for syntax: 
monospace indicates commands, keywords, and switches that should 
be spelled exactly as shown. These arguments may or may 
not be optional, depending on whether they are enclosed 
in square brackets. 

italic indicates arguments for which you supply a value. 


[ ] (square 
brackets) 
. . . (ellipsis) 

| (vertical 
bar) 


indicate an optional argument when they surround the 
argument. 

indicates that you can repeat the argument or group of 
arguments preceding the ellipsis any number of times, 
means to choose one item from a group of items separated 
by the bars. 


The following example illustrates these syntax conventions: 
env [function | integer ] 


env 

is a command name, so it appears in monospace type. 
function 

is a function for which you supply the name, so it appears in italic 
type. 
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[function | integer] 

are both optional, so they are enclosed in square brackets. 
function | integer 

indicates that you can specify only one of the items separated by the 
vertical bar. 


Additional Documentation 

The following sections list documentation you may find helpful in using 
the SAS/C Development System. 

SAS If you are interested in SAS documentation, you need to contact Book 
Documentation Sales by writing, calling, or faxing the Institute: 

SAS Institute Inc. 

Book Sales Department 
SAS Campus Drive 
Cary, NC 27513 
Telephone: 919-677-8000 
Fax: 919-677-8166 

SAS/C Development System 

This book is part of a set of publications for the SAS/C Development 
System. There are three other publications in the set: 

□ SAS/C Development System User’s Guide, Volume 1: Introduction, 
Compiler, Editor describes how to 

□ install the SAS/C Development System on your Amiga 

□ use your development environment 

□ create files in the editor 

□ compile and link C files. 

□ SAS/C Development System User’s Guide, Volume 2: Debugger, Utilities, 
Assembler describes how to use 

□ CodeProbe, the SAS/C Source Level Debugger 

□ utilities such as smake, grep, scopts, and scmsg 

□ the SAS/C Macro Assembler 

□ the global and peephole optimizers. 

□ SAS/C Development System Quick Reference contains reference tables 
for the library functions, compiler and linker options, and debugger 
commands. 


These volumes are sold together as a set. 
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Other The following sections list additional reference material specific to the 
Documentation C language, Amiga and AmigaDOS programming, and the Motorola 68xxx 

microprocessor. 

C Language 

The following books describe the C programming language: 

American National Standards Committee (1990), American National 
Standard for Information Systems — Programming Language C, Document 
Number X3J11/90-013, Washington, DC: X3 Secretariat: Computer 
and Business Equipment Manufacturers Association. 

Harbison, Samuel P. and Steele, Guy L., Jr. (1990), C: A Reference 
Manual, Third Edition, Englewood Cliffs, NJ: Prentice-Hall, Inc. 

Kernighan, Brian W. and Ritchie, Dennis M. (1988), The C Programming 
Language, Second Edition, Englewood Cliffs, NJ: Prentice-Hall, Inc. 

C+ + Language 

The following books describe the C+ + programming language: 

Ellis, Margaret A. and Stroustrup, Bjarne. (1990), The Annotated C+ + 
Reference Manual, Reading, MA: Addison-Wesley Publishing Company. 

Ranade, Jay and Saba, Zamir. (1992), C+ + Primer For C Programmers, 
New York, NY: McGraw-Hill, Inc. 

Sessions, Roger. (1992), Class Construction in C and C++: object- 
oriented programming fundamentals, Englewood Cliffs, NJ: Prentice- 
Hall, Inc. 

Stroustrup, Bjarne. (1991), The C+ + Programming Language, Second 
Edition, Reading, MA: Addison-Wesley Publishing Company. 

Amiga and AmigaDOS 

The following books provide information specifically about programming 

on the Amiga. Most of the examples in these books are written in C or 

assembler. 

Commodore-Amiga, Inc. (1991), Amiga Hardware Reference Manual, 3rd 
Edition, Reading, MA: Addison-Wesley Publishing Company. 

Commodore-Amiga, Inc. (1991), Amiga ROM Kernel Reference Manual: 
Devices, 3rd Edition, Reading, MA: Addison-Wesley Publishing 
Company. 

Commodore-Amiga, Inc. (1991), Amiga ROM Kernel Reference Manual: 
Includes and Autodocs, 3rd Edition, Reading, MA: Addison-Wesley 
Publishing Company. 

Commodore-Amiga, Inc. (1991), Amiga User Interface Style Guide, 
Reading, MA: Addison-Wesley Publishing Company. 
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Commodore-Amiga, Inc. (1991), The AmigaDOS Manual, 3rd Edition, New 
York, NY: Bantam Books. 

Commodore-Amiga, Inc. (1992), Amiga ROM Kernel Reference Manual: 
Libraries, 3rd Edition, Reading, MA: Addison-Wesley Publishing 
Company. 

Motorola 68xxa 

The following books contain information specifically about programming 

the Motorola 68xxx microprocessor: 

Motorola, Inc. (1987), MC68881/MC68882 Floating-Point Coprocessor 
User’s Manual, First Edition, Englewood Cliffs, NJ: Prentice-Hall, Inc. 

Motorola, Inc. (1989), MC68030 Enhanced 32-Bit Microprocessor User’s 
Manual, Second Edition, Englewood Cliffs, NJ: Prentice-Hall, Inc. 

Motorola, Inc. (1989), Programmer’s Reference Manual, Phoenix, AZ: 
Motorola Literature Distribution. 

Contacting CATS You can contact Commodore Application and Technical Support at the 

following address: 


Commodore Business Machines, Inc. 
Department C 
1200 Wilson Drive 
West Chester, PA 19380 


215-431-9180 
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What Libraries Can I 
Access? 

1 Introduction 

1 Using the Shared Libraries 

2 Using Devices 

2 Using the Linkable Libraries 

3 Creating Your Own Libraries 


Introduction 

The SAS/C Development System includes several libraries. These libraries 
are of two types: 

shared libraries and devices 

are loaded when your program runs. Many of the shared libraries are 
included with the standard WorkBench disk and are in the libs : 
directory. These libraries have the .library filename extension. 
Devices are in the devs : directory and have the .device extension. 
Still others are in the system ROMs of your Amiga. 
linkable libraries 

contain code that is included in your program by the linker, for 
example sc . lib and s cm. lib. These libraries are in the lib: 
directory and have the .lib extension. 

The following sections describe each of the libraries supplied with your 
SAS/C software. 


Using the Shared Libraries 

Commodore provides many shared libraries, for example, 
version. library, di skf ont . 1 ibrary, and intuition, 
library. The autodocs available from Commodore describe the 
functions in these libraries. The autodocs are online text files, and you 
can purchase them from Commodore Amiga Technical Support (CATS) at 
the address listed under “Using This Book.” 



You can access the Commodore shared libraries (both ROM-based and 
disk-based) by one of the following methods: 

□ using the stub routines in the linkable library amiga.lib. For more 
information, see “Using amiga.lib”in Chapter 2, “Using the 
Commodore Libraries.” 

□ including the correct prototype file (for example, proto /dos .h) in 
your program. The prototype files contain prototypes and # pragma 
statements for each of the functions included in araiga . lib. “Using 
the Prototype Files” in Chapter 2 describes how to use the # pragma 
statements. 


Using Devices 

You use devices through exec system calls. Open the device with the 
OpenDevice function, then use the Do 10 family of exec calls. Refer to 
Amiga ROM Kernel Reference Manual: Devices for more information. 


Using the Linkable Libraries 

Your SAS/C software contains several libraries of standard ANSI C 
functions, C+ + functions, additional functions that are extensions to the 
ANSI C Standard, and functions that allow you to take advantage of your 
specific hardware configuration. 

The SAS/C software provides two standard linkable libraries: 

sc . lib is the SAS/C standard C library that contains all of 
the nonfloating-point routines described in 
Chapter 7, “C Library Reference” and in Chapter 8, 
“C+ + Library Reference.” 

s cm . 1 i b is the SAS/C standard C math library that contains 
all of the floating-point routines described in 
Chapter 7 and Chapter 8. 

Note: C+ + is not included if you install the SAS/C Development 
System on floppy disks. 



What Libraries Can I Access? 3 


The remaining libraries contain the same routines as the standard 
libraries, but are for use with various compiler options. The following 
libraries contain special versions of routines found in sc . lib: 

scnb. lib is for use with far addressing (absolute data 
addressing). 

scs . lib is for use with 16-bit integers, 
scsnb. lib is for use with 16-bit integers and far addressing. 

The following libraries contain special versions of routines found in 
s cm. lib: 


scmieee . lib 
scmf f p . lib 

scms . lib 

scm88 1 . lib 
scmnb . lib 


is the SAS/C math library for use with the 
Commodore IEEE shared library, 
is the SAS/C math library for use with the 
Commodore Motorola Fast Floating Point shared 
library. 

is the SAS/C math library for use with 16-bit 
integers. 

is the SAS/C 68881 coprocessor math library, 
is the SAS/C C++ math library for use with far 
addressing. 


Note: The standard libraries provide support for registerized 
parameters. To use registerized parameters, you must compile with the 
parms=register compiler option, but you do not need to link with a 
special library. 

Chapters 7 and 8 describe the functions contained in these libraries. 
Chapter 3, “Using the SAS/C Libraries,” describes how to access the 
linkable libraries. 


Creating Your Own Libraries 

You can also create your own shared or linkable libraries. For more 
information, see “Creating and Using Your Own Libraries” in Chapter 5, 
“Advanced Library Techniques.” 
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Using the Commodore’ 
Libraries 

5 Introduction 

5 Using amiga.lib 

6 Using the Prototype Files 

7 Defining Library Bases 


Introduction 

Normally, when you call a C or C+ + function, the compiler generates 
code to push the function parameters onto the stack. However, 
Commodore shared libraries expect to be called with parameters in 
specific registers, as described in the function description ( . f d) files from 
Commodore, and the library base in address register six (A6). You can 
solve this problem by using one of the following methods to access library 
functions: 

□ using the stub routines in amiga .lib 

□ using the # pragma statements in the prototype files. 

This chapter describes how to access the Commodore libraries using both 
methods (although using # pragma statements is preferred) and how to 
define library bases for the Commodore libraries. 


Using amiga.lib 

amiga.lib contains all the stub routines necessary to call the actual 
routines in the Commodore shared libraries. These stub routines take the 
parameters off the stack, put them into the correct registers, load the 
correct library base from an external variable, and call the actual routine. 

For example, the following code calls the Write and Output 
functions in dos. library using the stub routines in amiga.lib. (The 
startup code opens the library, so you do not need to call the 
OpenLibrary function.) 

void main(void) 

{ 

Write(Output( ) , "Hello WorldNn" , 12); 

} 



If this program is in a file named test . c, you can compile, link, and 
run test . c with the following Shell commands: 

sc LINK test.c 
test 

The compiler, sc, produces an object file, test . o, and a link file 
test . Ink. This link file is an ASCII text file that tells the linker, 
slink, which libraries to use when linking, (test . Ink is called a 
with file.) The compiler options that you specify in the sc command 
determine which libraries the compiler specifies in the with file. You can 
display the contents of test. Ink from a Shell by entering 
type test. Ink. 

In this example, the two libraries sc . lib and amiga . lib are 
searched when your program reaches the calls to Write and Output. 
The calls to the Write and Output functions are resolved using the 
stub routines in amiga . lib. 


Using the Prototype Files 

Instead of depending on the stub routines in amiga .lib, you can use 
# pragma statements in your code to access the system libraries. The 
prototype files in the include:proto directory include prototypes and 
# pragma statements for each of the functions included in amiga .lib. 

To use these statements, include in your program the correct header 
file from the include : proto directory. When you use these #pragma 
statements, the compiler can move function parameters into the correct 
registers, load the library base into register A6, and call the function 
directly, without the overhead required to use the stub routine. 

For the example described in “Using amiga . lib,” you would add the 
following line at the top of the test.c file: 

# include <proto/dos .h> 

You can compile, link, and run test.c as before. Although the 
test . Ink file still lists amiga .lib as a library to be searched, the 
Write and Output functions are not pulled from amiga .lib because 
the compiler does not generate a symbol reference to those functions. 
From the # pragma statements, the compiler already knows where the 
routines are and which registers they require. 

You can include all of the header files for the Amiga system libraries 
by including the following line in your program: 
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((include <proto/all.h> 

Including proto/all. h increases the compilation time required for 
your program. 

To access the functions in exec, library, the SAS/C Development 
System provides two different sets of # pragma statements: syscall and 
libcall. On machines with 68020 or higher processors, it is 
significantly faster to use the # pragma libcall because each 
syscall statement references memory location 4. Each libcall 
statement references a copy of location 4 in the program’s data area. 
References to low memory require more time on machines with 68020 
and higher processors. 

To use ipragraa syscall statements, simply include 
pr oto/ exec . h in your program. To use ((pragma libcall 
statements, follow these steps: 

1. Define the preprocessor symbol USE—SYSBASE. You can define 

this symbol on the command line or with a # define statement in 
your program. 

2. If you are not using one of the startup modules supplied by the 
SAS/C Development System, initialize the variable SysBase. To 
initialize SysBase, include the following definition in your 
program: 

struct ExecBase *SysBase = *(struct ExecBase **)4; 

3. Include proto/exec. h in your program. 

Defining Library Bases 

A library base contains the jump table for a library, and it is the value 
returned by a call to OpenLibrary. The most common place to store a 
library base is a global variable. However, you can declare the base to be 
anything you want. For example, you can declare the base as automatic 
or static, or you can enter a ff define statement such as 

((define DOSBase mystruct->myDOSBase 

You must include the # define statement before any reference to the 
base. 

Also, before calling the functions in a shared library, the library base 
must be initialized. 
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If you declare but do not define a system library base in your own 
code, the library base is automatically initialized. The autoinitialization 
code calls OpenLibrary to initialize the library base, and the 
autotermination code calls CloseLibrary to close the library. For more 
information on automatically initializing library bases, refer to Chapter 
10, “Using Startup Modules, Autoinitialization, and Autotermination 
Functions,” in SAS/C Development System User's Guide, Volume 1. 

You can explicitly initialize library bases using the OpenLibrary, 
OpenResource, and OpenDevice functions. With the exception of 
exec . library, if the library file has the extension . library or 
.class, initialize the base by calling the OpenLibrary function. 

struct Library *MyLibBase; 

MyLibBase = OpenLibrary( "name. library" , revision); 

MyLibBase = OpenLibrary( "name. class" , revision ); 

If the library file has the extension .resource, initialize the base by 
calling the OpenResource function. 

struct Library ^MyLibBase; 

MyLibBase = OpenResource( "name. resource", revision ); 

The revision number indicates the version of the operating system that 
you want to use. 


OS Library 
Version Revision 

1.2 33 

1.3 34 

2.0 36 (Preliminary 2.0) 

2.04 37 

2.1 38 

3.0 39 

3.1 40 
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If the library file has the extension .device, initialize the base as 
follows: 

struct Library *MyLibBase; 

OpenDevice( "name. device" , unit, lioreq, flags) ; 

MyLibBase=&ioreg. io_Device; 

The unit and flags are specific to the device. For more information, refer 
to the autodocs or to Amiga ROM Kernel Reference Manual: Devices, 
available from Commodore. 

The following tables list each of the Commodore shared library names, 
their library bases, and the header files in the include : proto 
directory that contain the # pragma statements and prototypes for the 
functions in those files. 

Note: Case is significant in the library base names. 


Table 2.1 Library Bases for 

. library Files 


Name* 

Base 

Header File 

amigaguide (3.0) 

AmigaGuideBase 

amigaguide . h 

asl (2.0) 

AslBase 

asl . h 

bullet (2.1) 

BulletBase 

bullet . h 

commodities (2.0) 

CxBase 

commodities . h 

datatypes (3.0) 

DataTypesBase 

datatypes . h 

diskf ont 

Diskf ontBase 

diskf ont . h 

dos 

DOSBase 

dos . h 

exec 

SysBase 

exec . h 

expansion 

ExpansionBase 

expansion . h 

gadtools (2.0) 

GadToolsBase 

gadtools . h 



( continued ) 


*Each of the library names listed in this table end with . library. For example, the full name of the intuition library 
is intuition, library. 
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Table 2.1 ( continued ) 


Name* 

Base 

Header File 

graphics 

Gf xBase 

graphics . h 

icon 

IconBase 

icon . h 

iffparse (2.0) 

IFFParseBase 

i f f par se . h 

intuition 

IntuitionBase 

intuition . h 

keymap (2.0) 

KeymapBase 

keymap . h 

layers 

LayersBase 

layers . h 

locale (2.1) 

LocaleBase 

locale . h 

lowlevel (3.1) 

LowLevelBase 

lowlevel . h 

mathf f p 

MathBase 

mathf fp . h 

mathieeedoubbas 

MathleeeDoubBasBase 

mathieeedoubbas . h 

mathieeedoubtrans 

MathleeeDoubTransBase 

mathieeedoubtrans .h 

mathieeesingbas 

MathleeeS ingBasBase 

mathieeesingbas . h 

mathieees ingtrans 

MathleeeSingTransBase 

mathieees ingtrans . h 

mathtrans 

MathTransBase 

mathtrans . h 

nonvolatile (3.1) 

NVBase 

nonvolatile . h 

rexxsyslib (2.0) 

RexxSysBase 

rexx . h 

translator 

TranslatorBase 

translator . h 

utility (2.0) 

UtilityBase 

utility . h 

workbench (2.0) 

Workbench3ase 

wb . h 


‘Each of the library names listed in this table end with . library. For example, the full name of the intuition library 
is intuition . library. 
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Table^^JAbra^^asesJor^OUier^Ues^ 
Name Base 


console . device 
input . device 
ramdrive .device 
timer . device 
battclock. resource 
battmem. resource 
card, resource (3.0) 

ciaa . resource 

ciab . resource 
misc . resource 
potgo . resource 
colorwheel . gadget (3.0) 
dtclass . class (3.0) 


ConsoleDevice 

InputBase 

Ramdr i veDevice 

TimerBase 

BattClockBase 

BattMemBase 

CardResource 

CiaBase 

CiaBase 

MiscBase 

PotgoBase 

Colorwheel Base 

DTClassBase 


Header File 
console . h 
input . h 
ramdrive . h 
timer . h 
battclock . h 
battmem. h 
cardres . h 
cia . h 
cia . h 
misc . h 
potgo . h 
colorwheel . h 


dtclass . h 
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Introduction 

As described in Chapter 1, “What Libraries Can I Access?,” the SAS/C 
Development System includes several linkable libraries. The names of 
these libraries indicate the type of routines in the library and, therefore, 
the compiler options you must use when linking with the libraries. The 
following sections describe the naming conventions for SAS/C libraries 
and the compiler options to use with each library. 


Determining Which Library to Use 

If you use the link option in the s c command line, s c automatically 
links your program with the correct libraries based upon the other 
options you specify. However, if you need to specify the slink command 
separately (for example, in a makefile), you need to specify the correct 
library yourself. 

If you know what type of library routines you need to use, you can 
determine the library you need to use by looking at the letters included in 
the library name. The names of the SAS/C libraries follow this format: 

sc[s][nb][m[ieee | ffp | 88 1 | nb]].lib 
where 

s indicates the library uses short integers, 
nb indicates the library uses far addressing (no base register), 
m indicates the library contains floating-point math functions. If the 
library is a math library, the library name extension indicates the 
type of floating-point routines supported by the library, as follows: 

none s cm . 1 i b contains standard SAS/C floating-point routines. 



ieee The library uses the Commodore IEEE math library, 
f fp The library uses the Motorola fast floating-point library. 

8 8 1 The library uses Motorola 68881/68882 instructions, 
nb indicates the library uses far addressing (no base register). 

Note: Each type of math library is mutually exclusive. You can 
use only one math library at a time. 

For example, scnb . lib uses far addressing, scs . lib uses 16-bit 
integers, and scsnb. lib uses far addressing and 16-bit integers. 

Because of disk space considerations, all possible libraries are not 
included in this software. The libraries supplied in this software are 
described under “Using the Linkable Libraries” in Chapter 1. 

Because not all possible libraries are included, some combinations of 
compiler options art; not supported. For example, combining the use of 
short integers with 68881 instructions would require a library named 
scms88 1 . lib, which is not supplied with this software. Therefore, the 
combination of compiler options shortint and math=68 8 8 1 is not 
supported. In addition, the combination of options shortint and 
math=ieee (scmsieee . lib) is not supported. The C+ + translator 
does not support the use of short integers or Motorola fast floating-point 
format. 

If you need a library that is not provided with the SAS/C Development 
System, contact the Technical Support Division at SAS Institute. 


Compiling with the Correct Library 

Certain compiler options tell the compiler which SAS/C library to use. 

The compiler chooses the correct libraries based on the option or 
combination of options you specify. 

The following lists show the compiler options you should specify for the 
types of library routines you need to use. 

parms=register 

tells the compiler to use registerized parameters, 
shortint 

tells the compiler to use short integers. This option is not valid for use 
with C+ + files. 
data = far or data = f aronly 

tells the compiler to use absolute data addressing. 
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The math= options are mutually exclusive and indicate the type of 
floating-point math to be used, as follows: 

math= standard 

tells the compiler to use standard SAS/C floating-point routines. 
math=ieee 

tells the compiler to use Commodore IEEE routines. 
math=f fp 

tells the compiler to use the Commodore Motorola fast floating-point 
routines. This option is not valid for use with C+ + files. 
math=6888 1 

tells the compiler to use Motorola 68881 instructions. 


Linking with the Correct Libraries 

You can run the compiler and linker (slink) as separate steps (call each 
tool explicitly), or you can specify the link option in the sc command to 
link your program automatically after it compiles. 

If you call slink separately, you must specify each library explicitly 
after the lib keyword. Make sure you link your libraries in the correct 
order. When you are linking more than one library, follow these rules: 

1. Specify any libraries you create first. 

2. Specify the math library, if necessary. 

3. Specify any additional nonmath libraries. 

4. Specify amiga . lib last. 

For example, to compile and link prog . c using short integers, you could 
call the compiler and linker separately as follows: 

sc shortint prog.c 

slink lib:c.o+prog.o to test lib libtscs.lib lib: amiga . lib 

If you want to compile and link your program with one command, 
enter the link option in addition to any other options you need on the 
sc command line. If the compiler does not find any errors in your 
program, it will look at the other options you specify, determine which 
libraries are needed, and call slink to link your program. The compiler 
will link the libraries in the correct order. The compiler uses the 
standard C library sc . lib if you specify link without any additional 
library options. If you specify math=standard and link without any 
additional library options, the compiler uses the math library s cm. lib 
and the library sc . lib. 
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For example, to compile and link prog, c with one command, use the 
link compiler option as follows: 

sc shortint link prog.c 

To compile and link a program using the standard C library, you can 
use the following command: 

sc link prog.c 

If prog.c uses floating-point math and you want to use only the 
standard floating-point library (s cm. lib), specify the math=standard 
option also: 

sc math=standard link prog.c 

To summarize, Table 3.1 shows the options you should use on the sc 
command line to compile and link with each library supplied with the 
SAS/C Development System. 


Table 3.1 

Options Required to 

Library 

Options 

Type of Library 

mipile and Link with 
Each Library 

sc . lib* 

link 

Standard C and C++ library 

scs . lib 

shortint 

link 

Version of sc . lib that uses 
16-bit integers 


senb . lib 

data=f ar 
link 

Version of sc . lib that uses 
far addressing 


sesnb . lib 

shortint 
data=f ar 
link 

Version of sc . lib that uses 
16-bit integers and far 
addressing 


s cm. lib 

math= standard 
link 

Standard math library 


semieee . lib 

math=ieee 

link 

IEEE math library supplied by 
Commodore 

(continued) 


* C + + is not included if you install the SAS/C Development System on floppy disks. 
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Table 3.1 

(continued) 

Library 

Options 

Type of Library 

scmf f p . lib 

math=f f p 
link 

Motorola fast floating-point 
math library 


scmnb .lib 

math= standard 
data=f ar 
link 

Math library that uses far 
addressing 


scms . lib 

math= standard 

shortint 

link 

Math library for use with 16- 
bit integers 


scm88 1 . lib 

math=6888 1 
link 

68881 coprocessor math 
library 


If you are porting C code from a machine with short (16-bit) integers, 
you should compile with the shortint option. The shortint option 
tells the compiler to use 16-bit integers instead of the normal 32 bits. 
Any code compiled with the shortint option must be linked with a 
library whose name contains the letter s after the sc. 

If you have too much near data, you use the far keyword in the 
declarations and definitions of some of your larger data structures to 
move them into the far data section. Continue adding the far keyword 
until the near data section is less than 64K. If your program does not 
have a large data structure, you can use the data=far option (which 
tells the compiler to use 32-bit references) to force all data into the far 
section. For more information on near and far data sections, refer to 
Chapter 12, “How the Compiler Works” in the SAS/C Development 
System User’s Guide, Volume 1: Introduction, Compiler, Editor. 


Using the Math Libraries 

The standard math library, s cm . 1 i b, contains all of the floating-point 
routines described in Chapter 7, “C Library Reference” and in Chapter 8, 
“C+ + Library Reference.” The other math libraries contain special 
versions of the routines in s cm. lib. 



The following list contains additional information about using the math 
libraries. 

scm. lib 

is the standard math library. You must specify a math library if your 
program performs floating point operations. To use this library, 
specify the math== standard option on the compiler command line. 
This library ignor es any math coprocessors that may be present, s cm . 
lib uses the IEEE format for floating-point numbers, 
scmieee .lib 

calls the IEEE shared math libraries supplied by Commodore to 
compute floating-point operations. Advantages of using this library 
include: 

□ smaller executable code size. Code size is reduced because much of 
the code needed to perform the floating-point operations is in the 
shared library. 

□ optional 68881 or 68882 support. The Commodore IEEE library 
uses the 68881 or 68882 chip, if it is present, thereby making your 
program run much faster. If a math coprocessor chip is not present, 
your program will still run. 

The Commodore routines are slightly slower than their counterparts in 
scm. lib if a coprocessor is not present, and they do not adhere to 
the ANSI C Standard when dealing with mathematical errors, 
scmf fp. lib 

performs its operations in Motorola Fast Floating-Point (FFP) format. 
The FFP routines are faster than the IEEE routines, but they obtain 
this speed at the expense of accuracy. The precision of an FFP double 
is half that of an IEEE double. However, for many applications, FFP 
accuracy is sufficient. 

The compiler manipulates real numbers in the FFP format if you 
specify the math==f fp option. Do not mix the FFP and IEEE formats. 
If one module in an executable uses the math=f fp option, then all 
modules must use it. 

This library calls mathf f p . library and mathtrans . library, 
which are supplied by Commodore. These libraries do not adhere to 
the ANSI C Standard when dealing with mathematical errors, 
scms . lib 

is the same as the standard math library except it uses 16-bit integers. 
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scm88 1 . lib 

is the SAS/C Coprocessor Math Library. To get the best performance 
from this library, include the m68 88 1 .h header file (# include 
<m68 8 8 1 . h>) and compile with the math=68 8 8 1 option. Programs 
linked with this library will not run on a machine without a 68881 or 
a 68882 coprocessor, 
scmnb .lib 

is the same as the standard math library except it uses far addressing. 

If you call floating-point math routines in your program, but you have 
not compiled or linked with the correct options, you will get messages 
such as: 

Undefined Symbol: CXxnn 

To correct the problem, specify the correct compiler option for the library 
you need: math=standard, math = ieee, math=f fp, or 
math=6888 1, as described earlier in this chapter. If you want the 
compiler to call slink automatically to link your program, you must also 
specify the link option. 
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Introduction 

The system header files contain all of the function prototypes and 
# define statements needed by the libraries. This chapter describes how 
to use header files to reduce the amount of code produced by your 
program and the time required to compile your program. This chapter 
describes how to do the following: 

□ compress header files 

□ use the built-in functions in the string. h and stdlib.h files 

□ use Global Symbol Tables (GSTs). 

Using Header Files 

The following sections define header files and describe how to use the 
header files that are distributed with the SAS/C Development System. 

What are header Header files are ASCII text files that contain commonly used information 
files? for the compiler, such as function prototypes, # pragma statements, 

structure definitions, and symbol definitions. Header files are frequently 
referred to as headers or includes. By convention, C and C++ header 
files have a . h filename extension, and assembler header files have a . i 
extension. The ANSI C Standard recommends that you provide function 
prototypes for every function that you call, both for functions that you 
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write and those contained in the libraries provided by Commodore and 
by SAS Institute. The C+ + language requires prototypes. Including 
prototypes allows the compiler to check the number and type of function 
parameters and to detect possible errors in the way you call a function. 
For example, many of your programs probably use the standard function 
printf . Each program needs the following prototype: 

extern int printf (const char *, ...); 

All of the prototypes for the standard I/O functions, including printf 
are included in the file sc : include/stdio . h. To get the prototype for 
printf, as well as the other standard I/O functions, such as f printf, 
s printf, and scanf, just add the following line to the top of your file: 

((include <stdio.h> 

The compiler includes the header stdio . h from the include : 
directory in your pr ogram, and it treats your program as if you had 
added all of the prototypes for the standard I/O functions to your C 
source file. It is important that you include the correct header file rather 
than declaring the prototype yourself. By including the correct header 
file, you are including all of the necessary definitions, as well as the 
prototypes. 

All of the header files provided with SAS/C Development System are in 
the scrinclude and scrcxxinclude directories. These directories 
are normally referenced as include: and cxxinclude:. The 
installation program adds the necessary assign statements to your 
startup file. For more information, refer to Chapter 1, “Installing Your 
SAS/C Development System,” in SAS/C Development System User’s Guide, 
Volume 1. 

What headers do The sc: cxxinclude directory contains header files for the C+ + 

I have? functions described in Chapter 8, “C+ + Library Reference.” The 
sc : include directory contains header files for the C functions 
described in Chapter 7, “C Library Reference,” and for functions in the 
Commodore shared libraries. 
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Headers for C+ + Functions 


If you list the files in the scicxxinclude directory, you see the 
standard headers for the functions that are described in Chapter 8: 
complex. h libc.h stream. h 

fstream.h memory. h strstream.h 

iomanip.h new.h 

iostream.h stdiostream. h 


Headers for Standard C Functions 

If you list the files and subdirectories in the sc:include: directory, 
you see the standard headers for the functions that are described in 
Chapter 7: 


assert . h 

ios 1 . h 

signal . h 

ctype . h 

limits . h 

sprof . h 

dirent . h 

locale . h 

stat . h 

dos . h 

m6888 1 .h 

stdarg . h 

errno . h 

math . h 

stddef . h 

error . h 

memwatch . h 

stdio . h 

f cntl . h 

mf f p . h 

stdlib . h 

f ctype . h 

mieeedoub . h 

string . h 

float . h 

scrcntl . h 

strings . h 

functions . h 

set jmp . h 

time . h 


There are also several subdirectories under the sc: include 
directory. The sys subdirectory contains headers that are for use with 
the UNIX-compatible functions that are described in Chapter 7: 
dir.h stat.h types. h 

Headers for Commodore Shared Libraries 

Except for the sys subdirectory, the include: subdirectories contain 
headers that are for use with the shared libraries. Some of these header 
files were created by SAS Institute, and the rest are provided to you 
through a license agreement between SAS Institute and Commodore- 
Amiga, Inc. 



The following subdirectories were created by SAS Institute: 

pragmas contains headers with tfpragma statements for each of the 
Commodore shared libraries. For a complete description of 
# pragma statements, see Chapter 5, “Advanced Library 
Techniques.” 

proto contains headers with statements that include the 
appropriate files from the c 1 i b (which contains 
prototypes) and pragmas subdirectories. The proto 
headers also supply an extern statement for the 
necessary library base variable. 

Each of the shared libraries has a corresponding header 
file in the proto directory. These headers have the same 
name as the library but have the . h extension. 

The remaining files were provided by Commodore-Amiga, Inc. For 
complete information about using these headers and the features they 
describe, refer to the Amiga ROM Kernel Reference Manual: Includes and 
Autodocs and Amiga ROM Kernel Reference Manual: Libraries. These 
manuals describe how to use many special features of the Amiga and 
include sample code (usually written in C). 

If the name of a subdirectory matches the name of one of the shared 
libraries, the header files in that subdirectory contain structure 
definitions, # define statements, and other information needed by 
functions in that library. These subdirectories are listed in the following 
table: 


include : 

Subdirectory 

datatypes 

diskf ont 

dos 

exec 

graphics 

intuition 

utility 

workbench 


Shared Library 
datatypes . library 
diskf ont .library 
dos . 1 ibrary 
exec . library 
graphics . library 
intuition. library 
utility . library 
workbench. library 
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Where does the 
compiler look for 
include files? 


The include: directory also contains the following subdirectories: 

clib contains headers with function prototypes for the shared 
libraries. 


libraries 

devices 

hardware 

gadgets 

pref s 
resources 
rexx 


contains headers necessary when dealing with shared 
libraries in general, either while using them or while 
creating them. For information on creating and using 
your own shared libraries, see Chapter 5. 
contains headers with necessary items for using the 
Amiga standard devices, such as timer . device, 
serial .device, and so on. 
contains headers needed to define and access specific 
Amiga hardware features. Generally, you do not need 
these files unless you are a hardware designer, 
contains headers needed when accessing Amiga system- 
supplied BOOPSI gadgets, such as the colorwheel and 
gradientslider gadgets (as used in the system Palette 
Preferences program). 

contains headers with the descriptions of the data files 
used by the Amiga system Preferences programs, 
contains headers needed for dealing with Amiga 
resources, such as mi sc . resource, 
contains files needed when programming for use with 
AREXX. For more information on AREXX, refer to 
Chapter 7, “Using the AREXX Interface to se," in SAS/C 
Development System User’s Guide, Volume 1. 


When you include a file with the # include statement, the compiler 
searches a series of directories until it finds the file. The search path for 
include files differs slightly between C and C++. 

1. If the file was included with double quotes around its name (instead 
of less than and greater than signs), the compiler searches the 
current directory. 

2. The compiler searches the directory containing the current file. If 
the current file is a header file that includes another header file, the 
directory may differ from the current directory. 
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Which headers 
do I need? 


3. The compiler searches any directories that you specified with the 
Inc ludeDi rectory option in the order in which you specified 
them. 

4. At this point, the search path varies depending on whether you are 
compiling a C program or a C + + program: 

□ If you are compiling a C program, the compiler looks in 
include : . 

□ if you are compiling a C+ + program, the compiler searches the 
cxxinclude: directory, and if it does not find the file, it 
searches the include: directory. 

If the compiler finds the file in include : , C+ + considers it 
to have "C" linkage, not "C++" linkage. You do not need to add 
extern "C"{ } around the # include statements for any 
system files or SAS/C files in include:. 

Which headers you include in your program depends on which functions 
you use. 

The functions described in Chapters 7 and 8 are in the linkable 
libraries provided by SAS Institute. To use one of these functions, you 
need only include the correct header file from the include :, 
include :sys, or cxxinclude: directories. For each function, the 
correct header files are shown in Chapters 7 and 8 in the Synopsis 
section for each function or class. 

To use a function in one of the Commodore shared libraries, include 
the following in your program: 

□ any headers necessary for the function you want to use. The Amiga 
ROM Kernel Reference Manuals provide reference information for the 
various functions in each of the shared libraries. You can determine 
which library a function is in by searching the Include : clib 
directory for the function name using the grep utility or AmigaDOS 
search command. 

□ the prototypes and # pragma statements for the library containing the 
function. The easiest way to get both the prototypes and # pragmas is 
to include the appropriate file from the include : proto directory. 
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For example, you might want to use the AmigaDOS OpenWindow 
function. This function is in intuition, library. To use this function 
efficiently in your program, you need to include both of the following 
statements: 

((include <intuition/intuition.h> 

((include <proto/intuition.h> 

The file intuition/ intuition . h contains the definitions of data 
structures such as Menu and NewWindow, ((define statements for 
IDCMP flags, and so on, needed to use OpenWindow correctly. The file 
proto/intuition. h contains the appropriate function prototypes and 
((pragma statements and allows you to get the best possible code from 
the compiler. Both files work together to make sure the library is used 
correctly with the least amount of overhead in the program. 

You have probably noticed that several headers in different directories 
have the same or similar names. For example, there is both an 
include : stdio . h and an include : clib/stdio_protos . h. It is 
very important that you include the correct file for your purpose. Both of 
the previously mentioned files declare the function print f , for example, 
but they declare it differently. 

If you want to call the ANSI C Standard functions provided as a part of 
the SAS/C libraries, you should include the includerstdio.h header 
because the root level include : headers are all for use with SAS/C 
functions. If, however, you want to call the AmigaDOS version of the 
function, you should include the include : clib/stdio_protos . h 
file. 


Compressing Header Files 

Compressed headers require less disk space than uncompressed headers. 
The compiler can read header files in both compressed and uncompressed 
forms. You handle each form the same way; you do not have to specify 
anything special on your command line or in an # include statement. 
Also, you can have compressed and uncompressed header files within the 
same directory. 

Note: The C+ + translator does not support compressed headers. If 
you intend to program in C+ + , do not compress your C header files. 

The C headers are also used by the C++ translator. 



To compress a header or source file, enter the s compact command as 
follows: 

scompact source-file destination-file 

To compress all header files in a directory, enter the source file directory 
as the source-file and the destination directory as the destination-file. To 
compress all header files in a directory and its subdirectories, append the 
ALL keyword, as follows: 

scompact source-directory destination-directory ALL 

The utility compresses the files by encoding commonly occurring Amiga 
keywords. 


Using Built-in Functions 

Built-in functions, which are encouraged by the ANSI C Standard, allow 
the compiler to exploit register contents. When you use built-in functions, 
the compiler produces less code than if you called the library function. 
For example, if you use the built-in function strlen, the compiler does 
not generate code if the input string is a constant string. Instead, the 
compiler just returns the length and the string. 

Also, a built-in function that returns a pointer will not return the 
pointer if the pointer is unused. 

Your SAS/C software contains the following built-in functions: 

abs getreg memset strcmp 

emit memcmp printf strcpy 

geta4 memcpy putreg strlen 

When your program calls the printf function, the compiler examines 
the formatting string, and takes one of the following actions: 

□ If the formatting string is a constant string with no substitutions, the 

compiler changes the printf call to a writes call. 

□ If the formatting string is a constant string and contains only %s, %d, 

and %p formats, the compiler calls the tinyprintf function. 

tinyprintf is a private function that you should not call directly. 

The compiler will call tinyprintf if you include the stdio .h 

file. 



Using the System Header Files to Access Libraries 29 


The # define statements in the header files string.h and 
stdlib . h are set to call the built-in functions (except for print f, 
which is in stdio . h). To use these functions, you must include the 
correct header file. If you do not want to use the built-in functions, you 
can modify the appropriate function with an #undef statement after 
including the header files. For example, if your program contains an 
#undef strcmp statement, strcmp will be accessed as a real function 
call, not as a built-in function. 


Using Global Symbol Tables 

Note: The GST option is ignored when compiling C++ source files. 

In a typical development environment, processing header (include) files 
takes far more time than processing the source file itself. You can use 
Global Symbol Tables (GSTs) to reduce significantly the processing time 
required for C header files. A GST is a collection of all the information 
defined in a set of header files, stored in a format that the compiler can 
use easily and quickly. 

If you have a GST for your project, the compiler reads the information 
in the GST and stores it in memory. Then, when you include a header 
file in your program, the compiler looks in the GST before it searches any 
of the directories in the normal search path. If the header information is 
already in the GST, the compiler does not process the header file. If the 
header information is not in the GST, the compiler will read the header 
file, but if the header file is included more than once, the compiler does 
not read it again. 

Once the information from the header files is in the GST, the headers 
do not need to be present to compile the source file. Your source file 
must still contain the # include statements for the appropriate header 
files or the GST symbols will not be visible to your program. This 
behavior is different from Version 5 precompiled header files. To get the 
Version 5 behavior, compile with the gst immediate option. Previous 
versions of the SAS/C Development System included precompiled header 
files. GSTs are an improved version of precompiled header files. 
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Creating a GST To make the compiler generate a GST, compile your C program with the 
makegst compiler option, as follows: 

sc makegst GST-filename program-filename 

You can use any filename for the GST-hlename. A consistent naming 
convention will help you recognize GSTs. For example, you can compile 
header . c and use the filename header. gst by entering the following 
command: 

sc makegst header. gst header. c 

When the compiler creates a GST file, only the data in your header files 
and system header files are included in the GST. Data in the C source 
file, including any # define statements, are ignored. Therefore, you can 
use a normal project C source file to generate a GST. (In previous 
versions of the SAS/C Development System, you need a separate C source 
file to generate a precompiled header file.) 

Any objects declared in a GST are assumed to be external variables 
(extern). Therefore, these objects must be defined in one of the C 
modules to be linked into the executable file. If you prefer to place only 
system header files in the GST, you can use include:all.gst, a 
generic GST file than comes with the SAS/C Development System. The 
source file used to build this GST is included in sc:source/all.c. Use the 
following command if you want to rebuild all . gst: 

sc noobjname mgst=include:all.gst all.c 

Using a GST To use a GST, specify the gst option on the sc command line. You can 
specify the gst option only once per compilation. For example, if your 
GST is named project, gst, you can compile pro ject . c by entering 
the following command: 

sc gst=project.gst project. c 
You could use the generic system GST file by entering: 

sc gst=include:all.gst project. c 

The GST you specify is loaded into memory, and s c compiles your 
program. If you are using floppy disks, and you plan to remove the disk 
containing the GST from the drive, then you should load the GST using 
the gst utility before you compile your program. For complete 



Using the System Header Files to Access Libraries 31 


Header File 
Restrictions 


information on managing GSTs, refer to the description of the gst utility 
in Part 2, “Using SAS/C Utilities,” of the SAS/C Development System 
User’s Guide , Volume 2. 

There are some restrictions on the contents of the header files that can be 
included in a GST. If a header file does not meet these restrictions, you 
must not include it in the GST. These restrictions are as follows: 

□ Header files that you want to include in a GST cannot define data items 

or functions, including functions defined with inline. You can 

declare a data item and include function prototypes, but you cannot 
define data items or functions. 

The difference between a declaration and a definition is that a 
definition actually allocates storage for a variable or function, but a 
declaration only informs the compiler of the item’s type. For example, 
the statement int x ; defines an integer data item called x. The 
statement extern int x; declares x but does not define it. 

If the header file included in the GST contains a data definition, the 
data definition is treated as if it were a declaration. Storage is not 
allocated for the item, and unless it is defined elsewhere, the item 
shows up at link time as undefined. Any static initializer expressions 
generate an error message. 

□ Header files that you want to include in a GST must define the same 
preprocessor symbols to the same values no matter which source file in 
the project includes the GST. 

A GST is precompiled, so you cannot change what symbols it defines 
by changing preprocessor symbols at compile time. For example, the 
following file defines different symbols if the preprocessor symbol 
MAIN — C is defined: 

jfifdef MAIN—C 
((define x 1 
((else 

((define x 2 
(fendif 

The previous lines will not work in a GST file. If the symbol 

MAIN C was defined when the header was added to the GST, then x 

will be 1; if not, x will be 2. In both cases, x will be the same value 
for all source files in the project, regardless of whether MAIN_C was 
defined for that source file. 
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Introduction 

As described in Chapter 2, “Using the Commodore Libraries,” you can 
access the Commodore shared libraries using stub routines or using 
# pragma statements. You can also access other shared libraries using 
stub routines and # pragma statements, and you can create your own 
libraries. 

This chapter describes how to do the following: 

□ replace link library functions with your own functions 

□ create your own # pragma statements to access library functions 

□ use the fd2pragma utility to create # pragma statements 

□ create your own shared or linkable libraries. 


Replacing Link Library Functions With Your 
Own Functions 

The SAS/C Development System, Version 6, does not have separate 
libraries for use with registerized parameters. The normal link libraries 
have both registerized and nonregisterized entry points. 

If you write a function that has the same name as a library function, 

you need to add the regargs keyword to your function or compile 

with the parms=both or parms = register option. For example, you 
may want to replace the SAS/C library function malloc with your own 
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version of mall oc. If you compile with the parms = stack option or 

define your version of mall oc with the stdargs keyword, then two 

versions of malloc are linked into your executable module; one version 
from your code and one version from the library. If you use other SAS/C 
library functions that call malloc, these functions use the version of 
malloc in the SAS/C libraries. However, your functions that call 
malloc use your version of malloc. To make sure that all calls to 
malloc are using your version of malloc, define your version with 

regargs or compile with the parms=both or parms = register 

option. 

For information on using registerized parameters, refer to the 

description of the regargs keyword in Chapter 11, “Using SAS/C 

Extensions to the C and C+ + Languages,” and the description of the 
parameters compiler option in Chapter 8, “Compiling and Linking 
Your Program,” in SAS/C Development System User’s Guide, Volume 1. 


Using #pragma Statements 

When you access functions with a # pragma statement, the compiler 
moves library function parameters into the correct registers, loads the 
library base into register A6, and calls the function. If you do not use 
# pragma statements, the compiler pushes the function parameters onto 
the stack, calls the stub routine which takes the parameters off the stack, 
places them into the correct registers, and then calls the function. 

Using # pragma statements reduces program run time. However, the 
code generated by this technique does not usually show any significant 
savings in size over code generated using stub routines. 

You can write your own # pragma statements, or you can use the 
f d 2 pragma utility to generate the # pragma statements. 


Creating Your 
Own #pragma 
Statements 


Your SAS/C software supports seven types of # pragma statements: 

libcall allows you to call any library routine. This statement passes 
all parameters through specified registers, 
ami call allows you to call any library routine. This statement passes 
all parameters through specified registers, but you specify 
registers differently than with #pragma libcall. 
flibcall allows you to call most library routines. This statement 
allows you to use floating-point registers FP0-FP7. 


syscall allows you to call a routine in exec . library. This 

statement passes all parameters through specified registers. 
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tagcall allows you to call any library routine and pass parameters 
through registers and the stack. 

regcall is used for calls to functions defined in your own code. This 
pragma tells the compiler to pass parameters in specific 
registers, as if you had declared the function with the 
asm keyword. 

msg allows you to enable and disable errors and warnings. For 
more information, refer to the SAS/C Development System 
User’s Guide, Volume 1: Introduction, Compiler, Editor. 

#pragma libcall 

The libcall statement has the following format: 

# pragma libcall base function offset magic 
where 

base specifies the pointer to the library base. 
routine is the name of the function you want to call. 
offset specifies the offset from the library base of the function in 

hexadecimal format. You can get offset values from the function 
description (. fd) files.* For example, the offset value for the 
AllocMem function in exec .lib is C6 (decimal 198). 

Note: The offsets are subtracted from, not added to, the 
library base. 

magic describes the register conventions expected by the function. The 
following section, “Calculating the Magic Value,” describes how 
to determine magic values. 

For example, to call the Open function in dos . library, enter the 
following statement: 

ipragma libcall DOSBase Open 1e 2102 


* To make sure you get an accurate value, check the files on your disks instead of 
relying on the published listing of those files in the AmigaDOS manuals. 



#pragma amicall 

# pragma amicall is provided for compatibility with Aztec C. 

The amicall statement has the following format: 

Spragma amicall( base , offset , [retreg= ]function ( reg 1 [ , reg2 ].. . [regn ] ) ) 


base specifies the name of the library base. 
offset specifies the offset from the library base of the function in 

hexadecimal format. You can get offset values from the function 
description (. fd) files. * For example, the offset value for the 
AllocMem function in exec . lib is C6 (decimal 198). 

Note: The offsets are subtracted from, not added to, the 
library base. 

retreg= specifies the register for the return value. The default register is 
DO. 

function is the name of the function you want to call. 

regn specify the registers in which you want to pass parameters to 
the function. You can specify registers DO to D7 and AO to A6. 
You cannot specify floating-point registers. 

#pragma flibcall 

The #pragma flibcall statement allows you to pass parameters to 
the routine in floating-point registers. The # pragma flibcall 
statement follows the same format as the # pragma libcall statement; 
however, the compiler uses the information you specify in the magic 
value differently. The following section, “Calculating the Magic Value,” 
describes the differences. 


* To make sure you get an accurate value, check the files on your disks instead of 
relying on the published listing of those files in the AmigaDOS manuals. 
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#pragma syscall 

If the library you want to access is exec, library, you can use the 
syscall form of the # pragma statement: 

# pragma syscall function offset magic 

The #pragma syscall statement is roughly equivalent to a flpragma 
libcall statement using SysBase as the library base: 

# pragma libcall SysBase function offset magic 

However, # pragma syscall always reads the value of ExecBase 
from memory location 4, not from the actual SysBase. Reading low 
memory is slow on machines with 68020 and higher processors. 

#pragma tagcall 

The #pragma tagcall statement allows you to pass a varying number 
of parameters to the routine because some parameters are passed through 
the stack. The ^pragma tagcall statement follows the same format as 
the #pragma libcall statement; however, the compiler uses the 
information you specify in the magic value differently. The following 
section, “Calculating the Magic Value,” describes the differences. 

#pragma regcall 

The #pragma regcall statement tells the compiler to treat the 
previous prototype for the specified function as if you have declared the 

prototype with the asm keyword. The prototype must appear before 

the # pragma regcall statement, and it must not be declared with 

regargs, stdargs, or asm. The compiler generates an error 

if it cannot find the prototype for the function specified. 

#pragma regcall is provided for compatibility with Aztec C. 

The regcall statement has the following format: 

# pragma regcall ( [D0 = function (regl[ , reg2]...[regn]) ) 
where 

D0 = rg specifies the register DO for the return value. The return 
register is optional, but if specified, must be DO. Any other 
register generates an error message. 
function is the name of the function you want to call. 
regnl specify the registers in which you want to pass parameters to 

the function. You can specify registers DO to D7, AO to A6, and 
FPO to FP7. 

If the function definition is included in the current compilation, it may be 
declared with the asm keyword or with no special register keywords. 
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Calculating the 
Magic Value 


The format of the magic number used in some pragmas is as follows: 
nmlkjihgfedcbaR # 


The lowercase letters a through n are hexadecimal numbers that specify 
registers corresponding to the parameters in right to left order. In other 
words, a is the leftmost parameter, and n is the rightmost parameter. For 
the fpragraa libcall and ^pragma syscall statements, the 
hexadecimal numbers designate the registers into which the first through 
the fourteenth function parameters should be placed. 

For the # pragma tagcall statement, each hexadecimal number you 
specify, except the last, designates a register into which a parameter 
should be placed. The last number designates a register that contains a 
pointer to all parameters that are not placed into registers. (These 
parameters are placed on the stack and referred to as the taglist.) 

For the # pragma flibcall statement, each parameter is designated 
by two hexadecimal digits that represent a floating-point register such as 
FPO, FP1, or FP7. 

The following table lists hexadecimal numbers you should use to 
designate specific registers. 


Table 5.1 

Register Conventions 


Value 

(Hex) 

Register 

Value 

(Hex) 

Register 

Value 

(Hex) 

Register 

0 

DO 

8 

AO 

10 

FPO 

1 

D1 

9 

A1 

11 

FP1 

2 

D2 

A 

A2 

12 

FP2 

3 

D3 

B 

A3 

13 

FP3 

4 

D4 

C 

A4 

14 

FP4 

5 

D5 

D 

A5 

15 

FP5 

6 

D6 

E 

A6 

16 

FP6 

7 

D7 



17 

FP7 


Note: Address register A7 is never used as part of a # pragma 
statement. Register A7 is the stack pointer. If register A6 is used, the call 
is considered a special case. Register A6 must point to the library base. 
Therefore, if you load a parameter into register A6, this parameter is 
used as the library base, and the library base specified on the # pragma 
call is ignored. 
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The uppercase R specifies the register where the result is returned. 

This number is usually 0 for data register DO, although there are no 
restrictions as to which register you may select for return values. 

The # value specifies the total number of parameters passed to the 
routine in registers. You must specify this value in hexadecimal, and it 
can be up to 14 (a hexadecimal E) for ^pragmas libcall, tagcall, 
and syscall. This value can be up to 6 for #pragma f libcall. 

For example, refer to the synopsis of the AmigaDOS Open function in 
the Amiga ROM Kernel Reference Manual: Libraries. 

file = Open(name, accessMode) 

DO D 1 D2 

Table 5.1 gives the hexadecimal value for register DO as 0, the value for 
register D1 as 1, and the value for register D2 as 2. The Open function 
takes two parameters and returns the result in register DO. Therefore, the 
magic value for the call to the Open function is 2102. 

As an additional example, refer to the synopsis of the AmigaDOS 
OpenLibrary function in the Amiga ROM Kernel Reference Manual: 
Libraries. 

library = OpenLibrary! libname, version) 

DO A1 DO 

Using the information in the following table, you can calculate the magic 
value for the OpenLibrary function as 0902: 


Magic 

Number Meaning 
0 Register for version (DO) 

Register for libname (Al) 

Register for the result, library (DO) 
Number of parameters 


9 

0 

2 
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To illustrate the # pragma tagcall statement, suppose you have a 
function called rayfunc that can take a variable number of parameters. 
Suppose the function myfunc has two parameters followed by any 
optional taglist parameters. You can use myfunc with a # pragma 
tagcall statement with a magic value of 98103. The first parameter 
would be placed into register Dl, the second into register AO, all 
remaining parameters would be placed on the stack, and the address of 
the first parameter on the stack would be placed into register Al. 


Generating 
#pragma 
Statements with 
the fd2pragma 
Utility 


The format of the ff pragma statements is relatively easy to understand 
and code but difficult to maintain and or decode. However, you can 
create a standard ASCII function description ( . f d) file, and use the 
fd2 pragma utility to create a header file containing the corresponding 
# pragma statements. 


Creating a function description (.fd) file 

A function description file consists of instructions ( directives ) to the 
fd2 pragma utility, the entry points of each library function, and 
comments. You can enter only one statement per line. Comments begin 
with an asterisk (*); instructions to the f d2pragma utility begin with two 
pound signs (##); any other line is an entry point into a library function. 
For example, the following lines are from the dos_lib . f d file: 


* "dos . library" 
ffffbase _D0SBase 
ff ffbias 30 
ffffpublic 

Open(name,accessMode) (d1/d2) 

Close( file) (dl ) 

Read(file,buf fer , length) (d1/d2/d3) 

* 

If lend 


The fd2pragma utility accepts the following instructions: 

# ffbase name identifies the global variable pointing to the base of 
the library. 

ff jfbias n identifies the offset value between the library base and 
the entry point of the first function in the library. 

This value should usually be 30. 

ffffpublic identifies subsequent functions as being available to 
your programs. 
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##private identifies functions as being available to the library 
only. Programs cannot call functions designated as 
private. This instruction is useful if you are 
distributing your . f d file to other people, and you do 
not want them to use some of the functions in your 
. f d file. Several of the headers provided by 
Commodore use ##private statements. 

# #end Marks the end of the file. 

You must include entry points for all of the functions in your library 
that can be called by another program. The entry points follow this 
format: 

entryname(arguments)(registers) 

Use commas to separate the arguments. Use commas or slashes (/) to 
separate registers. 

Note: Commas are used to separate entries that need to be pushed 
with separate move or movem assembler instructions. Slashes indicate 
those entries that can be combined in a single movem instruction. 

For example, the following lines are from the intuition, library 
file: 


InitCode(startClass, version) (D0/D1 ) 

PrintIText(rp, itext, left, top) ( A0/A1 ,D0/D1 ) 

Running the fd2pragma utility 

To run the f d2pragma utility, enter the f d2pragma command as 
follows: 

fd2pragma infile, fd newheader. h 
where 

infile specifies the function description file that you created. The 
. f d extension is required. 

newheader specifies the file where you want the new # pragma 
statements stored. The . h extension is required. 

If the fd 2 pragma utility encounters any errors, the errors are printed 
in the standard output file. For example, your function description file 
could contain invalid directives, invalid register specifications, or no 
##end statement. 



Using the f d 2 pragma utility is less likely to lead to errors than trying 
to amend the # pragma statements themselves. It is strongly suggested 
that you always maintain the function description file and use the 
fd2pragma utility. 


Creating and Using Your Own Libraries 

A linkable library, in its simplest form, is a concatenation of object 
modules. An object module is the output of the compiler and cannot be 
run. Object modules are used by the linker, slink, to create the final 
executable module. 

You can create your own linkable libraries using the Object Module 
Librarian (OML) or the AmigaDOS JOIN command. To use your custom 
linkable library, you must link with it before you run your program. If 
you have code that rarely changes and is used in multiple projects, you 
should create a linkable library. 

You can create shared libraries using sc and the f d 2 pragma utility. 
To use your custom shared library, you do not need to link with it, but 
you must call the OpenLibrary function before you can access any of 
your library’s routines. You should create a shared library if one or more 
of the following are true: 

□ you have code that must be shared among more than one program. 

□ you have a code layer that needs to do different things depending on 
run-time information. 

□ you have code that will rarely be used and you want to save system 
memory. 

You should name your linkable libraries with the .lib filename 
extension; name your shared libraries with .library; and name your 
devices with .device. 

The following sections describe how to create and use your own 
linkable and shared libraries. 

Note: You create and use devices and shared C+ + libraries in the 
same way that you create shared libraries in C. “Custom Shared C 
Libraries (Load at Run Time)” describes the basic steps for creating a 
shared C library, a shared C+ + library, and a device. “Custom Devices 
(Load at Run Time)” and “Custom Shared C+ + Libraries (Load at Run 
Time)” describe any different or additional steps required to create 
devices and shared C+ + libraries. 
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Custom Linkable 
Libraries (Link at 
Link Time) 


You can create a custom linkable library with one command, either JOIN 
or oml. To use your new library, you must specify the library in the sc 
or slink command line. 

When a function is included from a library, all other functions from 
the same source file are also included in your executable module by the 
linker. Therefore, you may want to place different functions in different 
files before creating your library. The following sections describe the 
steps necessary to create and use a linkable library. 

Creating the library 

To create linkable libraries, you can use the JOIN command as follows: 
JOIN object-files to library 

For example, you could create libl .lib from three separate object files 
with the following command: 

JOIN objl.o obj2.o obj3.o to libl. lib 

The . o and .lib extensions are required. 

Using the JOIN command has disadvantages. First, if you change an 
object module, you cannot replace that one object module in the library 
with the updated version. You must recreate the library. Second, the 
linker cannot efficiently look up a symbol in this type of library because it 
has to scan all the object modules. 

Using the Object Module Librarian (OML) produces a more efficient 
library. To create a new library with the OML, enter the oml command 
as follows: 

oml library r ofiles 

For example, to create the same library as shown in the JOIN command, 
you would enter the following oml command: 

oml libl. lib r objl.o obj2.o obj3.o 

You should give your library name the .lib file name extension. 

The letter r is a command that tells the OML to replace the object files 
in the library or add them if they are not already present. The OML also 
supports additional commands and options. For a complete description of 
the OML, refer to the SAS/C Development System User’s Guide, 

Volume 2: Debugger, Utilities, Assembler. 

The OML uses an indexing scheme that makes symbol lookup much 
faster for the linker. You can also replace single object modules without 
rebuilding the entire library. 
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Custom Shared C 
Libraries (Load at 
Run Time) 


Calling functions in the library 

To use your new library, you must link with it. To link in your custom 
libraries, specify each library in the sc command, as follows: 

library 3 .lib UbraryZ .lib 

For example, librmylib. lib dfO :yourlib. lib tells the linker 
to search the libraries lib:mylib. lib and df 0 :yourlib. lib before 
it searches the default libraries. 

The linker also includes the basic run-time support library, 
lib: sc . lib, and the AmigaDOS binding library, lib: amiga . lib, 
after it includes the libraries you specify. 

To compile a program called pr og . c and link in the library created in 
the previous examples, libl .lib, you would enter the following 
command: 

sc link libl. lib prog.c 

The compiler puts libl .lib in the list of libraries to be searched 
before the standard libraries. The with file that is passed to slink is as 
follows: 

FROM lib:c.o prog.o 
to prog 

lib libl. lib lib:sc.lib lib:amiga.lib 

Creating a custom shared library is more complicated than creating a 
linkable library. You need to know how to create function description 
files. 

You can create two types of shared libraries: 

A library with one near data section 

With this type, all tasks that open the library share the same data 
space. Extra care should be used when accessing the near data to 
avoid non-reentrant functions. (With Version 5 of the SAS/C 
Development System, this type of library was the only type available.) 
Libraries with one near data section cannot call any link library 
functions that use external data. These functions include print f , 
malloc, and many others. 

To create this type of library, link with libinit.o as described in 
the following section. 
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A library that copies the near data section 

With this type, each task that opens the library uses a separate near 
data section, but all openers share the same far data section. The 
library copies the near data section and passes the library base to the 
task that opens the library. That is, each call to the OpenLibrary 
function returns a different library base. (This technique is similar to 
the technique cres . o uses for resident programs.) 

To create this type of library, link with libinitr.o as described 
in the following section. 

The following sections describe restrictions on shared libraries and the 
steps necessary to create and use shared C libraries, shared C+ + 
libraries, and exec-level devices (which are a type of shared library), 
sc : examples/samplelib and sc : examples/reslib both contain 
an example of creating a shared library. 

Restrictions on Shared Libraries 

For a library with one near data section, all tasks that open the library 
get the same far data section and, if using libinit.o instead of 
libinitr.o, the same near data section. Therefore, if two programs 
open your library at once, you must not write to the library’s global data 
in a way that will affect the other program. 

If you modify the provided libinit.c file, you cannot refer to global 
data in this file. You can call a function in another file that refers to 
global data, slink does not fix up global data references in the 
libinit . c file. 

Shared libraries are limited to 32K of near data. (Programs can have 
64K of near data.) 

If your library requires any custom initialization code, and if you create 
your library using libinitr.o, then you can use autoinitialization and 
autotermination functions. If you use libinit.o, you must place any 

initialization code in a User Libinit function as described in the 

next section, “Creating the library from C code.” 

From within a shared library, you must not call any library functions 
that terminate your program. For example, you cannot call exit, 

exit, or abort from a shared library. You also cannot use set jmp 

and long jmp to jump across a call from the program into the library. 

If your shared library uses dos. library calls or link library I/O 
functions, and if it is opened by a task instead of a process, your machine 
will crash. Most programs on the Amiga run as processes. For more 
information on tasks and processes, refer to the Amiga ROM Kernel 
Reference Manual: Libraries. 



Creating the library from C code 

The following steps are the basic steps required to create a shared 
library. If you are creating a shared C+ + library or a device, read the 
sections “Custom Shared C+ + Libraries (Load at Run Time)” or 
“Custom Devices (Load at Run Time),” respectively, before continuing 
with these steps. 

To create a shared library from C code, follow these steps: 

1. Decide if your library will have one near data section for all tasks 
or a separate section for each task. 

2. Determine which functions will be called from outside your library 
and the registers in which they take their parameters. For each 
function: 

a. declare the function using the asm keyword, and declare its 

parameters with the register keyword, two underscores, 
and the register into which you want the parameter placed. 

For more information, refer to “Specifying Registers for 
Parameters” in Chapter 11, “Using Assembly Language with 
the C and C+ + Languages,” in the SAS/C Development System 
User’s Guide, Volume 2. 

b. add the saveds keyword to the function definition. For a 

description of saveds, refer to Chapter 11, “Using SAS/C 

Extensions to the C and C+ + Languages,” in SAS/C User’s 
Guide, Volume 1. 

3. Create a function description file (. fd) describing your library using 
the information in “Creating a Function Description (. fd) File,” 
earlier in this chapter. The register information should match the 
function declarations. 

4. If your library requires any custom initialization code, and if you 
create your library using libinitr.o, then you can use 
autoinitialization functions. If you use libinit.o, you must place 

any initialization code in a UserLiblnit function with the 

following prototype: 

int saveds asm UserLiblnit 

(register a6 struct MyLibrary *libbase); 

Place any required initialization code, such as opening libraries or 
allocating memory, into this function. This function will be called by 
the initial startup code of the library if you are using one data 
section or by the OpenLibrary function if you are using separate 

data sections. If UserLiblnit is successful, it should return a 

0; otherwise, it should return a nonzero value. If a nonzero value is 
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returned, the startup code for the library aborts, and the library is 
not opened. 

Any system resources allocated by the UserLiblnit routine 

must be freed. To do so, create a function with the following 
prototype in your source code: 

void — saveds asm UserLibCleanup 

(register — a6 struct MyLibrary *libbase); 

Place all cleanup code, such as code to close libraries and free 

memory, into this function. The UserLibCleanup function will 

be called by the LibExpunge function just before the library is 
removed from the system if you are using one data section or by the 
LibClose function if you are using separate data sections. (These 
functions are called from lib: libinit. o.) 

5. Compile all modules with the libcode and nostackcheck 
compiler options. Do not use the stackextend or stackcheck 
compiler options to compile any of these modules. Do not use the 
stackext keyword on any of these functions. 

6. Create the library using the sc command, as follows: 

sc startup =lib-init-routine 
to libname. library 
link 

libfd fdfile 
[libprefix prefix] 

[libid idstring ] 

[lib link-libraries] 

[libVersion version] 

[libRevision revision] 
modules 

where 

lib-init-routine 

contains the system-required library entry points Open, Close, 
and Expunge, as well as other initialization routines. Specify 
either lib : libinit . o or lib : libinitr . o as described at 
the beginning of this section, libinit. c, the source for both 
libinit.o and libintr.o, is in the source subdirectory. 
fdfile 

specifies the name of the function description file you created in 
step 3. 



prefix 

specifies a prefix you want added to the functions listed in the 
function description file. The default is an underscore (_). 

Make sure that the function declarations in your source code 
match the full name, including any specified prefix, but 
excluding the leading underscore. For example, if your library 
has a function called myf unc and you specify a prefix of _LIB, 
you should declare the function in your source code as 
LIBmyf unc. 
idstring 

specifies a library identification string, slink uses this value to 
set the —LiblD symbol, but idstring is not required. 
libname. library 

specifies the resulting library name. You should give your 
library name the .library file name extension. 
link-libraries 

specifies any link libraries that you want the linker to search for 
modules referenced in your code. 
version 

sets the version number of the library you are creating. You can 
set the version number to any number from 0 to 255. The 
default is 1. 
revision 

specifies a minor revision number for your library. If you do 
not specify a revision number, it defaults to 0. 
modules 

specifies the modules that you want included in your library. 

7. Create # pragma statements for your library using the fd2pragma 
utility, f d2pragma produces a header file containing # pragma 
statements for all the externally callable functions in your library. 
See “Generating ipragma Statements with the fd2pragma 
Utility,” earlier in this chapter, for information on using 
f d2pragma. 
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Calling functions in the library 

To use the functions in the new library, follow these steps: 

1. Include the header file generated by the fd2pragma utility in your 
program. 

2. Declare a variable in your program of type struct Library 

* libbase, where libbase is the name of the library base you 
specified in your . f d file. The name of the library base is 
determined from the ##base instruction in the function description 
file. The library base can be an automatic or a global variable. For 
example, if your library is called my lib. library, and you named 
the library base MyLibBase, you would declare the library base as 
follows: 

struct Library *MyLibBase; 

3. Initialize the library base in your program by calling the 
OpenLibrary function. 

MyLibBase = OpenLibrary( "mylib. library" , version); 

The version number indicates the minimum version number of the 
library that you want to use. You can set the version numbers of 
any libraries that you create by specifying the version keyword in 
the sc command. A version of 0 will open any version. You must 
initialize the library base before calling any functions in the library, 
and you should check to make sure that the library base is not 
null. A null library base indicates that the library could not be 
loaded or that the version was not acceptable. 

4. Call whatever library functions are needed. You can call these 
functions by name, just like any other function. When one of the 
library functions is called, the compiler loads the parameters into 
the correct registers, loads the library base in register A6, and calls 
the function. 

5. Call the CloseLibrary function at the end of your program: 


CloseLibrary(MyLibBase) ; 



Understanding shared libraries 

To help you build your own libraries, the following sections describe 
what happens when you create a library using the information in the 
earlier section “Custom Shared Libraries (Load at Run Time).” These 
sections explain how multiple processes can access the same shared 
library simultaneously. 

What the compiler does 

Modules compiled with the libcode option do not use register A6, 
except when calling other libraries, in which case the value of the 
register is restored immediately on return from the library. Therefore, 
register A6 always points to the current library base. 

When you specify the saveds keyword and compile with the 

libcode option, the compiler generates the following instruction in the 
function prolog: 

LEA LinkerDB(A6) ,A4 

LinkerDB is a symbol generated by the linker that specifies the offset 
from the library base at which user global data may be stored. Therefore, 
the above instruction sets register A4 to point to the library’s global data. 

Note: The standard executable startup code, c . o, contains a reference 
to LinkerDB. When slink is linking a library, it interprets LinkerDB 
differently than when linking a normal program. 

What the Liblnit function does 

The Liblnit function is called when the operating system loads your 
library from the disk. The library is always loaded from the disk the first 
time it is used, but subsequent uses may reuse the version that is still in 
memory. 

Liblnit sets some flags in the library base and partially initializes the 
library base. It copies the near global data from the location pointed to by 
the symbol —Libmergeddata to the memory location directly following 
the library base, so that the data can be found later. 

If your library was linked with libinit . o, then the Liblnit 
function performs any necessary relocations to the new near data section 
and calls the —UserLiblnit function. 
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What the LibOpen function does 

The LibOpen function is called when a user program calls 
OpenLibrary on your library. The first time your library is loaded, the 
operating system loads the library, calls Liblnit, and then immediately 
calls LibOpen (since an OpenLibrary call prompted the operating 
system to load your library). As long as the system does not run low on 
memory, your library stays in memory after the user program exits, and 
the next call to OpenLibrary may find your library still in memory. In 
this case, Liblnit is not called, but LibOpen is called again. 

If your library was linked with libinit.o, the LibOpen function 
merely increments the usage count of your library and returns a pointer 
to the library base. 

If your library was linked with libinitr.o, the LibOpen function 
increments the usage count of the main library base, and then makes a 
copy of the library base. The copy includes the near global data area at 
the end of the library base, thus giving the new opener its own copy of 
the global data. The LibOpen function performs the necessary 
relocations on the new copy of the global data, then calls the standard 
function to initialize link library routines, autoinitialization routines, and 

C+ + constructors ( libfpinit). Finally, it calls —UserLiblnit 

for compatibility with Version 6.0 and 5.10 shared libraries. 

What the LibClose function does 

The LibClose function is called when a user program calls 
CloseLibrary on your library. LibClose decrements the usage count 
for your library. 

If your program was linked with libinit.o, the LibClose function 
does not do any other cleanup. 

If your program was linked with libinitr.o, the LibClose 
function calls the function —UserLibTerm for compatibility with 
Version 6.0 and 5.10 shared libraries. It then calls the standard function 
to terminate link library routines, autotermination routines, and C+ + 

destructors ( libfpterra). It then frees the copy of the library base 

allocated by LibOpen. 

What the LibExpunge function does 

The LibExpunge function is called when no user programs are 
currently using your library, and the operating system needs to free 
memory. If your program was linked with libinit.o, the 
LibExpunge function calls —UserLibTerm, and frees the copy of the 
near data allocated by Liblnit. If your program was linked with 
libinitr . o, the LibExpunge merely frees the copy of the near data 
allocated by Liblnit. 
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What the linker does 

First, slink reads the function description (. fd) file, determines the 
names and number of functions to the library, and creates a jump table 
of the following form: 

— LibOpen 
— LibClose 
— LibExpunge 
RomTag - 2 

user-defined functions 

The names of the user-defined functions are created by adding the 
specified prefix (see step 4 under “Creating the Library” earlier in this 
chapter) to the front of the function names in the function description 
file. The symbol _LibFuncTab points to this jump table, which is placed 
into the data section. 

slink communicates information to libinit.o by defining the 
following global symbols: 

_LibName is the name of the library, as specified by the to option to 
slink. 

_LibID is the library ID, as specified by the libid option to 
slink, slink sets this string to null if you do not 
specify a libid. 

RESLEN is the length of the data section to be allocated as part of 
the Library structure. 

newdatal is the length of the initialized data section. 

The libinit.o file references these symbols at startup to correctly 
initialize the library and all associated data. 

Understanding the format of shared libraries 

The following lines show the format of the library that slink produces. 

Code Hunk 1: (comes from libent.o) 


moveq 

rts 

RomTag 

If 0 , dO 

; This is in case someone tries 
; to run the library as a program 

dc.w 

RTC—HATCHWORD 

; RomTag information for the library 

dc.l 

_LibRomTag 

; as described in Rom Kernel manual 

dc.l 

endtag 

; 1 

dc.b 

RTF—AUTOINIT 

; 1 

dc .b 

VERSION 

; 1 
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dc .b 

NT—LIBRARY 

dc.b 

PRI 

dc.l 

_ LibName 

dc.l 

_LibID 

dc.l 

-LiblnitTab 


I 

I 

I 

v 

End of RomTag information 


Code Hunk 2 - n: (comes from libinit.o and user modules) 

—Liblnit 

<code for Liblnit> 

-LibOpen 

ccode for LibOpen> 

-LibClose 

<code for LibClose> 

-LibExpunge 

<code for LibExpunge> 
user functions 


DATA HUNK 

_Libmergeddata ; symbol that tells Liblnit where the merged 
; data is initially loaded. 

-LiblnitTab ; struct LiblnitTab as specified in libinit.c 

length of global data 
pointer to function jump table 
NULL 

pointer to initialization code (—Liblnit) 
user global data 


Custom Shared 
C+ + Libraries 
(Load at Run 
Time) 


You create and use shared C+ + libraries in the same way that you 
create shared libraries in C, as described in the previous section. The 
following sections describe any differences between C and C+ + shared 
libraries and any additional steps required to create a C+ + shared 
library. 


Declaring the C+ + functions in the library 

When you are declaring the C+ + functions that will be in your library, 
make sure that you do not use registers reserved for special parameters. 
The following list describes special considerations for declaring shared 
library functions in your C++ source files. 
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□ If you are using C+ + member functions as library entry points, 
register AO will be used to point to the this pointer for these 
functions. You cannot use register AO for your own parameters. In 

your source file, declare the member functions with the asm 

register keyword, but do not specify register aOfor any of the 

parameters. 

□ If you are using C+ + constructors or destructors as library entry 
points, register DO will be used to point to a hidden C+ + parameter. 

You cannot use register DO for your own parameters. Since 
constructors and destructors are member functions, you cannot use 
register AO either. 

In your source file, declare the constructors and destructors with the 

asm register keyword, but do not specify register aO or 

register dOfor any of the parameters. 

□ If you define a function that returns a class for which you have defined 
a copy constructor, and you are using the function as a library entry 
point, register A1 will be used to point to the area of storage used for 
the return value for the copy constructor. You cannot use register A1 
for your own parameters. 

In your source file, declare the function with the asm register 

keyword, but do not specify register al for any of the 

parameters. 

For more information about using asm to declare functions, refer to 

“Using the asm Keyword in Chapter 11, “Using Assembly Language 

with C and C+ + Languages,” in SAS/C Development System User’s 
Guide, Volume 2. 

Creating the .fd file 

When you create your function description file, you may need to add 
extra parameters for member functions, constructors and destructors. The 
following list describes special considerations for creating . f d files for 
C+ + shared libraries. 

□ Even though you do not declare a parameter in register AO in your 
C++ source file, you must modify the entries for C + + member 
functions in your . fd file to include the this parameter in register 
AO as the first parameter. 

For example, if your C+ + file includes the declaration 

— asm int F00: : func(register dl int x, register a2 char *y); 
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then the corresponding entry in the . f d file would be 
func 3F00FiPc(this,x,y) (A0,D1 ,A2) 

□ Even though you do not declare a parameter in register DO in your 
C+ + source file, you must modify the entries for C+ + constructors 
and destructors in your . f d file to include the hidden parameter in 
register DO as the second parameter. 

For example, for the FOO: : func function shown previously, the 
corresponding entry in the . f d file would be 

func — 3F00FiPc(this f xxx,x f y) (A0,D0,D1 ,A2) 

□ Modify the entries in your . f d file for functions that return a class for 
which you have defined a copy constructor so that the entries include 
the hidden parameter in register A1 as the third parameter (even 
though you do not declare a parameter in register A1 in your C+ + 
source file). 

Your . f d file must list the names of the functions in the library 
interface, just as you do when creating a shared library in C. However, if 
you are placing a C + + function in the library interface, you must list 
the C name that the C+ + translator generates for the function (that is, 
the mangled name) rather than the actual C+ + name. To find the 
mangled name, compile your C+ + module with the cxxonly option. 
Look at the generated C file. Search for the C++ name in the . . c file, 
and you should see the C function definition that corresponds to the 
C+ + definition. You can use the demangle utility to verify the C+ + 
name, demangle should print the name of the C+ + function in which 
you are interested. (For more information, refer to the description of the 
demangle utility in SAS/C Development System User’s Guide, 

Volume 2.) 

As an alternative, you can declare the interface functions to your 
library inside extern "C". The names of functions declared inside 
extern "C" are not mangled, and you can use them exactly like C 
function names. 

When you are using sc to create the library, you must use 
libinitr.o as the lib-init-routine instead of libinit.o if you intend 
to declare extern or static instances of classes. If you do not use 
libinitr.o, your constructors and destructors will not be run. 

C+ + constructors for data items declared inside the library will run 
when the user calls OpenLibrary. The corresponding destructors will 
run when the user calls CloseLibrary. 



56 Chapter 5 


Example of creating a shared C+ + library 

The following example illustrates the steps necessary to create a shared 
library in C++. 

1. Type in the following C+ + file and name it temp . cxx: 

class F00 

{ 

public: 

asm F00(register dl int init); 

asm ~F00( ) ; 

void asm foofunc(register dO int intparm); 

void asm foofunc(register al char *ptrparm) ; 

}; 


asm saveds F00: :F00(register — dl int init) 

{ 

) 

asm saveds F00::~F00() 

{ . 
) 

void asm saveds F00: : foofunc(register dO int intparm) 

( 

) 


void asm saveds F00: :foofunc(register al char *ptrparm) 

{ 

) 


2. Compile this file by entering the following command: 

sc temp. cxx cxxonly 

3. Use the editor to examine the C output produced by the compiler. 
Use the String Search option (Control-S) to find f oof unc. You will 
see two definitions of functions that start with f oof unc: a function 

called f oofunc 3FOOFi and one called f oofunc 3FOOFPc. 

These function are the mangled C versions of the C+ + functions 
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FOO : : f oof unc ( int ) and F00 :: f oof unc ( char *). Verify 
this by using the demangle utility from the Shell: 

1> demangle foofunc 3F00Fi 

FOO: :foofunc( int) 

1> demangle foofunc — 3F00FPC 
FOO: :foofunc(char *) 

Now search for the strings ctor and dtor. A function with the 
string ctor in its name is a C+ + constructor. A function with the 
string dtor in its name is a C+ + destructor. In this case, the 

constructor name is ctor 3FOOFi and the destructor name 

is dtor 3FOOFv. 

For more information on the demangle utility, refer to SAS/C 
Development System User’s Guide, Volume 2. 

4. Assuming your library base is called FOOBase, you would create 
the following . f d file: 

ffbase -FOOBase 
iffbias 30 
ffpublic 

foofunc 3F00Fi ( this , intparm) ( AO , DO ) 

foofunc 3F00FPc(this,ptrparm) ( AO , A 1 ) 

ctor 3F00Fi(this ,xxx, init) (AO ,D0 ,D1 ) 

dtor 3FOOFv( this, xxx) (AO, DO) 

fiend 

5. After you have created your . f d file, use the f d2pragma utility to 
generate pragmas and include the resulting pragmas into your C+ + 
programs. 

Initializing and terminating your library 

If you place C+ + constructor and destructor functions in your shared 
library, you must not attempt to declare instances of that class in the 
program using the library until after the library has been opened, and 
you must not close the library until all destructors have been processed. 

C+ + constructors and destructors for extern or static objects are 
run from an autoinitialization or autotermination function at priority 
5000. This means that you should include autoinitialization and 
autotermination functions in your program to open and close the library. 
This autoinitialization/autotermination function pair should have a 
priority number less than 5000. 
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The following example contains autoinitialization and autotermination 
functions that run at priority 4000 and open and close the library. 

/* Assume class F00 is actually defined in a shared library */ 

/* called "foo. library" . This code would be in the program */ 

/* that wants to use the library. */ 

class FOO 

( 

public: 

asm F00(register — dO int init); 

asm ~F00( ) ; 

void asm foofunc(register dO int intparm) ; 

void asm foofunc(register al char *ptrparm); 

); 

struct Library *F00Base; 

FOO f oo (10); /* This declares an extern instance of an object */ 

/* with type FOO. Since the definition is */ 

/* external, it causes the constructor */ 

/* FOO: :F00(int) */ 

/* to be called. The call will occur during */ 
/* autoinitialization at priority 5000. 

/* We need to make sure that the library is open at */ 

/* that time, so we declare an autoinitialization */ 

/* routine to do it. */ 

int _STI_4000_initFOO( void) 

{ 

FOOBase = 0penLibrary( "foo. library" , OL); 
if (FOOBase == NULL) 

( 

/* Error case - issue a message here */ 

/* Returning nonzero from this function */ 

/* causes us to terminate the program. */ 
return -1 ; 


) 


return 0; 
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/* Since the global destructors call the library as well, */ 
/* we can't close the library until after autoterm priority */ 
/* 5000. Declare an autoterm function with a lower priority*/ 
/* number to make sure this works correctly. */ 

void _STD_4000_termFOO( void) 

( 

if (FOOBase) CloseLibrary( FOOBase) ; 

FOOBase = 0L; 

) 

Custom Devices AmigaDOS devices are specialized shared libraries. You create and use 
(Load at Run exec-level devices in the same way that you create shared libraries in C, 
Time) as described previously in this chapter. The differences between devices 
and libraries are: 

□ System devices typically reside in devs : instead of libs : . 

□ Devices have a .device extension instead of a .library extension. 

□ The first two functions in the . f d file for a device must implement the 
Beg in IO and Abort 10 functions as described in Amiga ROM Kernel 
Reference Manual: Devices. Additional entries may be used for custom 
functions. 

See Amiga ROM Kernel Reference Manual: Devices for more information. 

To build a device, follow the instructions for creating a shared library 
in C, except for the following: 

□ Make sure that the first two functions listed in your . f d file implement 
BeginlO and AbortIO as described in Amiga ROM Kernel Reference 
Manual: Devices. 

□ Specify devinit.o or devlnitr.o as the lib-init-routine (instead of 
libinit.o or libinitr.o). 

□ Name your device with a .device extension instead of a .library 
extension. 
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6 Predefined Data Name 
Reference 


This chapter describes the predefined data names provided with the 
SAS/C software. These data names are external variables that you can 
read or write from your program. You can also form a pointer to any 
external name using the ampersand (&) operator. 

The data names are described in alphabetical order. Each data name 
description includes the following sections (if applicable): 


Synopsis 

Description 

Portability 


shows the declaration for the data name, including any 
header files that must be included in the calling routine, 
describes what the data name does, what it is used for, and 
which functions use it. This section also contains any 
additional details you need to use the data name, 
describes the systems or languages with which the data 
name is compatible. A data name’s portability falls into one 
of these categories: 


AmigaDOS indicates the data name can be used only 
under Commodore’s AmigaDOS. 

ANSI indicates the data name is compatible with the 
definition in the ANSI Standard for C. 

SAS/C indicates the name is in the SAS/C portable 
library. These data names are available only 
when using the SAS/C libraries and may or 
may not be equivalent to data names in 
libraries from other vendors. 


UNIX indicates the data name is compatible with 
AT&T’s UNIX System V or BSD 4.x UNIX. 


Example contains sample code showing how to use the data name. 
See Also lists related functions and data names. 
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-BackGroundIO Route I/O to the console window 


Synopsis § include <dos.h> 

long -BackGroundIO; 

Description The global variable —BackGroundIO is used by cback . o to indicate 
whether output will be sent to the console window by your background 
process. The default is 0, indicating that I/O will not be sent to the 
console window. 

Setting —BackGroundIO to 1 tells cback. o to initialize 
—Backstdout to point to the console window. If —BackGroundIO is 
set to 1, you must call Close on —Backstdout before the program 
exits: 


Close (-Backstdout); 

If you do not include this statement before your program exits, the CLI 
window pointed to by —Backstdout will not close properly. 

This variable is of interest only for background processes. If you do not 
link with cback . o, this variable is ignored. 

Portability SAS/C 

See Also —Backstdout 
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Backstdout 

Synopsis 

Description 


Portability 
See Also 


Pointer to the console window file handle 


# include <dos.h> 

BPTR -Backstdout; 

The global variable —Backstdout is used by cback . o to point to the 
console window where I/O is to be routed. —Backstdout is an 
AmigaDOS file handle, like the ones returned from the AmigaDOS 
function Open. If _ BackGroundIO is set to 1, cback. o initializes 
—Backstdout to point to the console window. Otherwise, 
—Backstdout is not initialized. If —BackGroundIO is set to 1 and 
—Backstdout is initialized, you must call Close for —Backstdout 
before the program exits. 

Close (-Backstdout); 

If you do not include this statement before your program exits, the 
Shell window pointed to by —Backstdout will not close properly. 

This variable is of interest only for background processes. If you do not 
link with cback . o, this variable is ignored. 

SAS/C 

—BackGroundIO 
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buffsize 

Synopsis 

Description 


Portability 
See Also 


Level 2 1/0 buffer size 
extern int buffsize; 

This external integer is used by the level 2 1/0 system to specify the size 
of the buffers allocated for level 2 files. This location is also used to 
specify the size of a buffer attached to a file with the setbuf or 

setvbuf function buffsize must be set to the size of the buffer 

before the setbuf or setvbuf function is called or before the first I/O 
operation; otherwise, the default buffer size is used. 

The buffer is not allocated when the file is opened. Instead, the first 
I/O operation causes the buffer to be allocated from the local memory 
pool if one has not been previously specified with the setbuf or 

setvbuf function. This means that if buffsize is changed between 

the f open call and the first I/O operation, the size of the buffer allocated 

for the file will be the value of buffsize at the time of the I/O 

operation, not the value when the file was opened. 

In Version 5.10 and earlier, this variable was named _buf siz. 

SAS/C 

fopen, setbuf 



Predefined Data Name Reference 65 


ctype 

Synopsis 

Description 


Portability 

Example 


Character class table 
((include <ctype.h> 

The external character array ctype is a table indicating the attributes 

of all ASCII characters. It is 257 bytes long; one byte per ASCII 
character plus one to handle the EOF character. The individual bits 
within the byte are set to indicate attributes as described below. 


Bit 

Value 

Meaning 

_U 

1 

uppercase alphabetic character 
(A-Z) 

_L 

2 

lowercase alphabetic character (a-z) 

_N 

4 

decimal digit (0-9) 

_S 

8 

white space 

_P 

16 

punctuation character 

_C 

32 

control character 

_B 

64 

blank 

_X 

128 

hexadecimal digit (0-9, A-F, a-f) 


All indexes are offset by one so that the table also handles the end-of- 
file character (-1). You must index the table by the character plus one. 

Normally, you will not need to access the array directly, but will 
instead use the is. . . character test macros (i supper, isascii, and 
others) to access it for you. 

In Version 5.10 and earlier, this variable was named _ctype. 

SAS/C 

((include <ctype.h> 


/* Modify the ctype array to treat the character 0x80 as */ 
/* white space. Change 0x81 to be an uppercase character. */ 
/* This means isspace() will return TRUE on 0x80, and */ 
/* isupper(), isalpha(), isalnum( ) , isprint(), and isgraph()*/ 
/* will return TRUE on 0x81. */ 
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ctype 

( continued ) 


See Also 


Character class table 


void main(void) 

( 

/* Make 0x80 a white space character */ 

— ctype [ 0x8 0+ 1 ] 1= _S; 

/* Make 0x81 an uppercase character */ 

— ctype [0x8 1 + 1 ] 1= _U; 

) 

isalnum, isalpha, isascii, iscntrl, isdigit, 
isgraph , islower, isprint, ispunct, isspace, 
isupper, isxdigit 
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daytbl 

Synopsis 

Description 


Portability 

Example 


See Also 


Array of days by name 
extern char * daytbl[]; 

The external array daytbl contains seven pointers to character 

strings representing the days of the week. Each string is three bytes long, 
plus a null terminator. The values are as follows: 


Index 

String 

Meaning 

0 

Sun 

Sunday 

1 

Mon 

Monday 

2 

Tue 

Tuesday 

3 

Wed 

Wednesday 

4 

Thu 

Thursday 

5 

Fr i 

Friday 

6 

Sat 

Saturday 


SAS/C 

/* Replace the day table with a French version. You */ 
/* might do this as a static DATA intialization if you */ 
/* know you will be in French; or, you could call this */ 
/* routine if and when the user selects French from a */ 
/* menu item somewhere. 

extern char * — daytbl [ ] ; 

void main (void) 

{ 


daytbl [ 0 1 

"Dim" ; 

/* 

Dimanche 

(Sunday) 

*/ 

— daytbl [ 1 1 

"Lun" ; 

/* 

Lundi 

(Monday) 

*/ 

daytbl [2] 

"Mar" ; 

/* 

Mardi 

(Tuesday 

*/ 

daytbl [3] 

"Her" ; 

/* 

Mercredi 

(Wednesday) 

*/ 

daytbl [4] 

"Jeu" ; 

/* 

Jeudi 

(Thursday) 

*/ 

daytbl [5] 

"Ven" , 

/* 

Vendredi 

(Friday) 

*/ 

— daytbl [6] 

"Sam" ; 

/* 

Samedi 

(Saturday) 

*/ 


) 

montbl, months 
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DOSBase 

Synopsis 

Description 


Portability 

Example 


AmigaDOS library vector 

extern struct DosLibrary *D0SBase; 

DOSBase = OpenLibrary( "dos. library" , revision) ; 

This external location is used by various Amiga library routines that 
interface with AmigaDOS system functions. It is initialized by an 
OpenLibrary call in the startup code and is expected to contain the 
base address of the AmigaDOS system library vector table. If you do not 
link with the startup module c . o, and if you make calls to AmigaDOS 
system functions or use SAS/C features that call AmigaDOS system 
functions, then you must first initialize this location by calling the 
OpenLibrary function. 

If you call the OpenLibrary function, you must close the library 
before your program terminates. 

For information about the revision parameter, see “Defining Library 
Bases” in Chapter 2, “Using the Commodore Libraries.” 

AmigaDOS 

/* This example demonstrates how to use OpenLibrary on */ 

/* dos. library to initialize DOSBase. It finishes by */ 

/* closing dos. library, as all programs which open it */ 

/* must do before terminating. */ 

({include <stdio.h> 

((include <stdlib.h> 

extern struct DosLibrary *D0SBase; 

void main(void) 

{ 

int ver =34; /* Revision number for AmigaDOS version 1.3 

DOSBase = (struct Library *) OpenLibrary ( "dos . library" , ver ) ; 
/* Make sure library opened OK */ 
if (DOSBase == NULL) 
exit (EXIT-FAILURE) ; 

/* Insert your code using DOSBase here ... */ 

CloseLibrary ((struct Library *)D0SBase); 

) 
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errno UNIX error number 

Synopsis jf include <error.h> 

extern int errno; 

extern int sys_nerr; 

extern char * sys_errlist[ ] ; 

Description The external integer errno is initialized to 0 at start-up time. Then, if an 
error is detected by one of the standard library functions, a nonzero 
value is placed there. The standard library never resets errno. 

Programmers typically use this information in two ways. In some cases, 
it is appropriate to check errno after a sequence of operations and abort 
if any error occurred along the way. In other cases, errno is checked 
periodically, and if it is nonzero, the appropriate corrective action is 
taken. Then, the application program resets errno before beginning the 
next processing phase. 

The sys_nerr and sys_errlist items are defined in a C 

source file named syserr . c and are used by the perror function to 
print messages that correspond to the code found in errno. 

Even though error information is normally placed into errno by the 
standard library functions, application programs can also use this 
technique to indicate problems. However, you should be careful about 
adding new codes and messages just above the highest UNIX code 
currently defined, since new UNIX codes are occasionally added. Also, it 
is recommended that you add application-dependent codes by extending 
the header file error .h, which contains symbolic definitions of the code 
numbers. The currently defined symbols are as follows: 


Symbol 

Meaning 

EOSERR 

operating system error 

EPERM 

user is not owner 

ENOENT 

no such file or directory 

ESRCH 

no such process 


(continued) 
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errno UNIX error number 
( continued ) 


Symbol 

Meaning 

EINTR 

interrupted system call 

EIO 

I/O error 

ENXIO 

no such device or address 

E2BIG 

arg list is too long 

ENOEXEC 

EXEC format error 

EBADF 

bad file number 

ECHILD 

no child process 

EAGAIN 

no more processes allowed 

ENOMEM 

no memory available 

EACCES 

access denied 

EFAULT 

bad address 

ENOTBLK 

block device required 

EBUSY 

resource is busy 

EEXIST 

file already exists 

EXDEV 

cross-device link 

ENODEV 

no such device 

ENOTDIR 

is not a directory 

EISDIR 

is a directory 

EINVAL 

invalid argument 

ENFILE 

no more files (units) allowed 

EMFILE 

no more files (units) allowed for this process 


( continued ) 
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errno 

( continued ) 

UNIX error number 


Symbol 

Meaning 


ENOTTY 

not a terminal 


ETXTBSY 

text file is busy 


EFBIG 

file is too large 


ENOSPC 

no space left 


ESPIPE 

seek issued to pipe 


EROFS 

read-only file system 


EMLINK 

too many links 


EPIPE 

broken pipe 


EDOM 

math function argument error 


ERANGE 

math function result is out of range 

Portability 

ANSI 


See Also 

-FPERR, 

perror 
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f mask Default protection bits for opening a file 

Synopsis extern unsigned long fmask; 

Description This external integer indicates the default protection for any file created 
by the SAS/C file I/O routines, including all ANSI I/O routines. This flag 
has no effect on AmigaDOS I/O routines such as Open. The default 
protection is read, write, and delete. 

You can modify fmask. To reset fmask, use the following 

values (defined in the f cntl . h file): 


Portability 


Value 

Meaning 

S—ISCRIPT 

script 

S—IPURE 

pure 

S—IARCHIVE 

archive 

S—IREAD 

read 

S_I WHITE 

write 

S-IEXECUTE 

execute 

S—IDELETE 

delete 


SAS/C 


See Also creat, f open, open 
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fmode 

Synopsis 

Description 

Portability 
See Also 


Default level 2 I/O mode 
extern int fmode; 

This external integer is used by the f open function to determine the 
translation mode to use when the programmer does not specify a mode in 
the f open call. For AmigaDOS, it is set to 0_ RAW, which specifies 
untranslated mode. 

SAS/C 

f open 
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_FPERR 

Synopsis 

Description 


Portability 

Example 


Floating-point error code 
((include <math.h> 

—FPERR contains a nonzero value after any low-level floating-point 
operation encounters an error. Low-level operations include addition, 
subtraction, multiplication, division, comparison, and conversion from 
one number representation to another (for example, floating point to 
double-precision floating point). 

The math.h file contains the declaration extern int _fperr, so 
you do not need to include this statement in your program. 

The following table lists the error codes and their corresponding 
symbols from the math.h file: 


Symbol 

Value 

Meaning 

_ FPEUND 

1 

underflow 

_ FPEOVF 

2 

overflow 

—FPEZDV 

3 

divide by zero 

_ FPENAN 

4 

not a valid number 

_ FPECOM 

5 

not comparable 


When the error occurs, the low-level operation passes the appropriate 
error code to the _CXFERR function, which must store the code in 
—FPERR. —FPERR is never reset by any low-level operation. 

For compatibility with previous releases, the error code values without 
the leading underscore are also defined in the math.h file unless you 
define the —STRICT— ANSI flag before including math.h. 

Note: This variable is only set when using the standard math libraries 
s cm. lib and scms .lib. 

SAS/C 

/* 

* This example uses the division operation to produce 

* floating point errors. For example, Enter 0 for the 

* divisor and 1 for the dividend to produce 

* _FPERR = 3 (Divide by zero). 

*/ 



Predefined Data Name Reference 75 


_FPERR Floating -point error code 
( continued ) 


linclude <math.h> 

((include <stdio.h> 

void main (void) 

{ 

double a,b,c; 

while(feof (stdin) == 0) 

( 

printf ( "Enter divisor: "); 

if (scant ("Xlf",ta) != 1) 
exit(0) ; 

printf ( "Enter dividend: "); 
if (scant ("J5lf" f 6b) != 1) 
exit(0) ; 

—FPERR = 0; 

c = b / a; 

printf ("-FPERR = *d\n", -FPERR); 
printf("Stlf / *lf = Xlf\n\n",b,a,c) ; 


) 


See Also errno 
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GfxBase 

Synopsis 

Description 


Portability 

Example 


Graphics library vector 

extern struct GfxBase *GfxBase; 

GfxBase = OpenLibrary ( "graphics . library" , revision) ; 

This external location is used by various Amiga library routines that 
interface with the ROM Kernel graphics system functions. It must be 
initialized by an OpenLibrary call before any of the graphics functions 
documented in the Amiga ROM Kernel manuals can be called. It is 
expected to contain the base address of the graphics library vector table. 
You must close the library before your program terminates. 

For information about the revision parameter, see “Defining Library 
Bases” in Chapter 2, “Using the Commodore Libraries.” 

AmigaDOS 

/* This example demonstrates how to use OpenLibrary on */ 

/* graphics . library to initialize GfxBase. It finishes */ 

/* by closing graphics . library, as all programs */ 

/* which open it must do before terminating. */ 

((include <stdio.h> 

((include <stdlib.h> 

extern struct GfxBase *GfxBase; 

void main(void) 

( 

/* Revision number for AmigaDOS version 1.3 */ 

int ver = 34; 

GfxBase = (struct Library *) 

OpenLibrary( "graphics . library" , ver) ; 

/* Make sure library opened OK */ 
if (GfxBase == NULL) 
exit ( EXIT-FAILURE ) ; 

I* Insert your code using GfxBase here ... */ 

CloseLibrary ((struct Library *)GfxBase); 

} 
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IntuitionBase Intuition library vector 

Synopsis extern struct IntuitionBase *IntuitionBase; 

IntuitionBase = OpenLibrary( "intuition. library" , revision ) ; 

Description This external location is used by various Amiga library routines that 

interface with the Intuition system functions. It must be initialized by an 
OpenLibrary call before any of the functions documented in the Amiga 
Intuition manuals can be called. It is expected to contain the base address 
of the Intuition library vector table. 

You must close the library before your program terminates. 

For information about the revision parameter, see “Defining Library 
Bases” in Chapter 2, “Using the Commodore Libraries.” 

Portability AmigaDOS 

Example /* This example demonstrates how to use OpenLibrary on */ 

/* intuition. library to initialize IntuitionBase. It */ 

/* finishes by closing intuition. library, as all */ 

/* programs which open it must do before terminating. */ 

((include <stdio.h> 

((include <stdlib.h> 

extern struct IntuitionBase *IntuitionBase; 

void main(void) 

( 

/* Revision number for AmigaDOS version 1.3 */ 

int ver = 34; 

IntuitionBase = (struct Library *) 

OpenLibrary ( "intuition. library" , ver ) ; 

/* Make sure library opened OK */ 
if (IntuitionBase == NULL) 
exit ( EXIT-FAILURE ) ; 

/* Insert your code using IntuitionBase here ... */ 

CloseLibrary ((struct Library *) IntuitionBase ) ; 

} 
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MathBase FFP library vector 

Synopsis extern struct Library *MathBase; 

MathBase = OpenLibrary( "mathffp. library" , revision) ; 

Description This external location is used to interface with the Motorola Fast Floating 
Point library routines provided by Amiga. It is initialized by an 

OpenLibrary call in the fpinit routine when a program compiled 

with the math=f f p option starts. It contains the base address of the FFP 
math library vector table. If you make direct calls to the Amiga FFP 
functions you must first initialize this location by calling the 
OpenLibrary function. 

You must close the library before your program terminates. 

For information about the revision parameter, see “Defining Library 
Bases” in Chapter 2, “Using the Commodore Libraries.” 

Portability AmigaDOS 

Example /* This example demonstrates how to use OpenLibrary on */ 

/* mathffp. library to initialize MathBase. It finishes */ 

/* by closing mathffp. library, as all programs */ 

/* which open it must do before terminating. */ 

((include <stdio.h> 

((include <stdlib.h> 

extern struct Library *MathBase; 

void main(void) 

I 

/* Revision number for AmigaDOS version 1.3 */ 

int ver = 34; 

MathBase = (struct Library *) 

OpenLibrary ( "mathffp. library" , ver ) ; 

/* Make sure library opened OK */ 
if (MathBase == NULL) 
exit (EXIT-FAILURE) ; 

/* Insert your code using Amiga FFP functions here ... */ 

CloseLibrary ((struct Library *)MathBase); 
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MathTranBase FFP transcendental library vector 

Synopsis extern struct Library *MathTransBase; 

MathTransBase = OpenLibrary( "mathtrans . library" , revision ) ; 

Description This external location is used to interface with the Motorola Fast Floating 
Point format transcendental function library routines provided by Amiga. 

It is initialized by an OpenLibrary call when a program compiled with 
the FFP option starts. It contains the base address of the FFP 
transcendental math library vector table. If you make direct calls to the 
Amiga FFP transcendental functions you must first initialize this location 
by calling the OpenLibrary function. 

You must close the library before your program terminates. 

For information about the revision parameter, see “Defining Library 
Bases” in Chapter 2, “Using the Commodore Libraries.” 

Portability AmigaDOS 

Example /* This example demonstrates how to use OpenLibrary on */ 

/* mathtrans. library to initialize MathTranBase. It */ 

/* finishes by closing mathtrans . library, as all */ 

/* programs which open it must do before terminating. */ 

finclude <stdio.h> 
finclude <stdlib.h> 

extern struct Library ^MathTranBase; 

void main(void) 

( 

/* Revision number for AmigaDOS version 1.3 */ 

int ver = 34; 

MathTranBase = (struct Library *) 

OpenLibrary ( "mathtrans. library" , ver) ; 

/* Make sure library opened OK */ 
if (MathTranBase == NULL) 
exit (EXIT-FAILURE) ; 

/* Insert your code using Motorola Fast Floating Point format 
transcendental functions here ... */ 

CloseLibrary ((struct Library * )MathTranBase ) ; 
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_MemType Type of memory desired 

Synopsis # include <exec/memory.h> 

extern unsigned long —MemType; 

Description The external long integer _MemType represents the type memory to be 
allocated by any of the memory allocation routines. The default is 
MEMF ANY. You can set —MemType to any of the following mnemonics: 

Mnemonic Value 

MEMF— ANY 0L (any type of memory will do) 

MEMF-PUBLIC 1L<<0 

MEMF-CHIP 1L<<1 

MEMF-FAST 1L<<2 

MEMF— LOCAL 1L<<8 

MEMF— 24BITDMA 1L<<9 (DMAable memory within 24 bits of 
address) 


These mnemonics are defined in the file exec /memory . h. 

Note: It is safe to change —MemType at any point in a program. 

Portability AmigaDOS 

Example If include <exec/memory.h> 

extern long -MemType; 

void main (void) 

( 

void *chipmem; 
void *fastmem; 
void *anymem; 
long oldtype; 


oldtype = -MemType; 
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MemType 

(continued) 


Type of memory desired 


/* allocate 50 bytes of any type of memory */ 
-MemType = MEMF-ANY; 
anymem = malloc(50); 

/* allocate 50 bytes of fast memory */ 
-MemType = MEMF-FAST; 
fastmem = malloc(50); 

/* allocate 50 bytes of chip memory */ 
-MemType = MEMF-CHIP; 
chipmem = malloc(50); 

-MemType = oldtype; 

) 


See Also malloc, AllocMemin the autodocs from Commodore 
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montbl 

Synopsis 

Description 


Portability 

Example 


Array of months by name 
extern char * montbl[]; 

The external array montbl contains twelve pointers to character 

strings representing the months of the year. Each string is three bytes 
long, plus a null terminator. The values are as follows: 


Index 

String 

Meaning 

0 

Jan 

January 

1 

Feb 

February 

2 

Mar 

March 

3 

Apr 

April 

4 

May 

May 

5 

Jun 

June 

6 

Jul 

July 

7 

Aug 

August 

8 

Sep 

September 

9 

Oct 

October 

10 

Nov 

November 

11 

Dec 

December 


SAS/C 

/* 

* Replace the month table with a German version 

* You might do this as a static DATA intialization if you 

* know you will be in German; or, you could change this into 

* a function that would be called if and when the user 

* selects German from a menu item somewhere 
*/ 

extern char * montbl[); 


void main (void) 
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months Array of month lengths 

Synopsis extern char months [ ] ; 

Description The external array months contains twelve characters, each 

representing the number of days in a specific month (in a non-leap year.) 
The values are as follows: 


Index 

Value 

Month 

0 

31 

January 

1 

28 

February 

2 

31 

March 

3 

30 

April 

4 

31 

May 

5 

30 

June 

6 

31 

July 

7 

31 

August 

8 

30 

September 

9 

31 

October 

10 

30 

November 

11 

31 

December 


Your programs must account for leap years when dealing with 
February. 

Portability SAS/C 
Example /* 

* This is a sample program demonstrating the use of months! ]. 

* Count the number of days since a given month and day. Assume 

* both dates are within the same calendar year. Assume month ana 

* date are BEFORE thismonth and thisdate. 
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_months 

(continued) 


Array of month lengths 


((include <stdio.h> 
extern char months! ]; 

int countdays( int month, int date, int thismonth, int thisdate) 

{ 

int days; 
int curmonth; 

if (thismonth == month) 
days = thisdate - date; 

else 

( 

days = months [month] - date; 

for (curmonth = month + 1; thismonth > curmonth; curmonth++) 

{ 

days += months [ curmonth ) ; 

) 

days += thisdate; 

) 

return(days ) ; 

) 

void main (void) 

( 

int x; 

/* Call countdays, print the result */ 
x = countdays (7, 12, 10,5) ; 
printf ("x = Xd \n",x); 


See Also daytbl, montbl 
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msflag 

Synopsis 

Description 

Portability 
See Also 


MS-DOS file pattern flag 
extern int msflag; 

This external integer is used by the filename pattern matching functions 

to specify AmigaDOS or MS-DOS wildcard characters. If msflag is 

nonzero, MS-DOS filename patterns are used. By default, AmigaDOS 
filename patterns are used. 

SAS/C 

dfind, getfnl 
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_MSTEP 

Synopsis 

Description 


Portability 
See Also 


Memory pool increment size 
extern long _MSTEP; 

This external integer is used by the memory allocation functions. It 
specifies the minimum amount of memory that will be allocated from the 
system for the local memory pool. The default value is 16,384 bytes. 

While additional memory is added to the local pool, it will not be 
contiguous with the memory already in the pool. If the additional amount 
is small, it can lead to severe fragmentation of the local pool. The 
memory allocation functions attempt to avoid this by rounding up the 
amount needed to the next multiple of the figure in _MSTEP. 

This technique works well for small allocation requests. However, if 
your application requires mostly large blocks of memory, _MSTEP should 
be set to a small nonzero figure to allow for a more efficient allocation. 

SAS/C 

free, malloc 
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nuf bs Count of level 1 file handle slots 

Synopsis ((include <ios1.h> 

extern int nufbs; 

Description The external integer nufbs indicates how many level 1 file handles 

exist in the uf bs linked list. 

In Version 5.10 and earlier, this data name was called _nuf bs. 
Portability SAS/C 
See Also ufbs 
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_oslibversion 

Synopsis 

Description 


Kickstart version number 
((include <dos.h> 
long oslibversion; 

If you declare but do not define a system library base in your own code, 
the library base is automatically initialized. The autoinitialization code 
calls OpenLibrary to initialize the library base. The autoinitialization 

functions pass the value of oslibversion to OpenLibrary. If 

your program runs only under a specific version of the operating system, 
declare this variable in your code and initialize it as necessary. For 
example, if your program requires Version 2.0 of the AmigaDOS 
operating system, which is library revision 37, you can enter the 
following line in your program external to any function: 

long oslibversion = 37; 

If your program is run under older versions of AmigaDOS, the 
autoinitialized libraries cannot be opened, and the library function 

autoopenfail is called. For more information, refer to Chapter 10, 

“Using Startup Modules, Autoinitialization, and Autotermination 
Functions,” in SAS/C Development System User's Guide, Volume 1. 

The following table lists the library revision numbers for each version 
of the operating system. 


OS Library 
Version Revision 

1.2 33 

1.3 34 

2.0 36 (Preliminary 2.0) 

2.04 37 

2.1 38 

3.0 39 

3.1 40 



90 Chapter 6 


oslibversion Kickstart version number 

(continued) 

Portability SAS/C 

Example 

extern long — oslibversion = 37; 

void main (void) 

( 

/* Insert your program here */ 

) 
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_OSERR DOS error information 
Synopsis i include <dos.h> 
extern int _0SERR; 

/* Number of AmigaDOS error codes */ 
extern int os_nerr; 

/* AmigaDOS error messages */ 
extern struct DOS_ERRS — os_errlist[ ] ; 

Description The external integer _OSERR contains error information returned by 
AmigaDOS after a system call has failed. In general, the SAS/C library 
resets _OSERR at the beginning of any function that makes AmigaDOS 
system calls. Then, if a system call fails during that function, the system 
error code is saved in _OSERR. 

The AmigaDOS error number is mapped into an equivalent UNIX error 
number, which is placed in err no. If there is no appropriate UNIX 
number, errno will contain — 1, defined symbolically as EOSERR. 

The os_nerr and os_errlist items are defined in a C 

source file named os err . c and are used by the poserr function to 
print messages that correspond to the code found in _OSERR. 

The following list of system error codes applies to AmigaDOS 2.0 and 
is contained in the file _oserr . c. The #def ine values for these codes 
are in the file dos/dos .h. 


Code 

Meaning 

103 

not enough memory is available 

105 

process table is full 

114 

bad template 

115 

bad number 

116 

required argument is missing 

117 

value after keyword is missing 


(continued) 
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_ OSERR DOS error information 
(continued) 


Code 

Meaning 

118 

wrong number of arguments 

119 

unmatched quotes 

120 

argument line is invalid or too long 

121 

file is not executable 

122 

invalid resident library 

202 

object is in use 

203 

object already exists 

204 

directory not found 

205 

object not found 

206 

invalid window description 

207 

object is too large 

209 

packet request type is unknown 

210 

object name is invalid 

211 

invalid object lock 

212 

object is not of required type 

213 

disk is not validated 

214 

disk is write-protected 

215 

rename across devices attempted 

216 

directory is not empty 

217 

too many levels 


( continued ) 
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_OSERR DOS error information 
(continued) 


Code 

Meaning 

218 

device (or volume) is not mounted 

219 

seek failure 

220 

comment is too long 

221 

disk is full 

222 

object is protected from deletion 

223 

file is write-protected 

224 

file is read-protected 

225 

not a valid DOS disk 

226 

no disk is in drive 

232 

no more entries are in directory 


The following error codes are defined only under AmigaDOS 2.0 and 
are documented in the dos/dos.h file. 


Code 

Meaning 

233 

object is soft link 

234 

object is linked 

235 

bad loadfile hunk 

236 

function not implemented 

240 

record is not locked 

241 

record lock collision 

242 

record lock timeout 

243 

record unlock error 


The following errors occur only when calling the MatchFirst 
function or Mate hN ext function or both functions of dos. library 
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OSERR DOS error information 
(continued) 

under AmigaDOS 2.0. These errors are documented in the 
dos/dosasl . h. 


Code 

Meaning 

303 

buffer overflow 

304 

break character received 

305 

not executable 


Portability AmigaDOS 

See Also AmigaDOS Technical Reference Manual, errno, poserr 
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—priority Default priority for a background program 
Synopsis # include <dos.h> 

long priority=-5; 

Description The global variable priority is used by the cback . o startup code 

to indicate the priority at which to start the background program. A value 
of 0 is the normal priority while larger values run at higher priority. 

This number is limited to the range —128 to 127, inclusive. 

You must initialize the variable at compile time. Setting this variable 
after the program has started does not affect the program priority. 

If you do not declare a priority variable, cback . o defaults to a 

priority of 0 (based on a default value drawn from the library). 

If you do not link with cback . o, this variable is ignored. 

Portability AmigaDOS 

Example /* A priority of 50 will ensure that your background program 

* runs. A priority this high will even prevent input 

* handlers from running, so the machine will be effectively 

* crashed by doing this (until your program calls 

* something that causes it to pause). 

* 

**** REMEMBER: You must link with cback. o for this variable 

**** to have any effect. 

*/ 

long priority=50; 

void main (void) 

I 

/* Insert your program here */ 

1 

See Also procname, stack 
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procname 

Synopsis 

Description 


Portability 

Example 


See Also 


Process name for a spawned program 
(finclude <dos.h> 

char * — procname="MyBackgroundProcess"; 

The global variable procname is the name that cback . o uses when 

spawning a background process. You may choose any name but should 
stick to something that is meaningful for your program. 

You must initialize this variable at compile time. Setting this variable 
after the program has started has no effect on the program name. Also, if 

the program is started from the workbench, the procname parameter 

is ignored. If you do not link with cback . o, this variable is ignored. 

AmigaDOS 

/* 

* Set the name of the background process. 

* 

***** REMEMBER: You must link with cback. o for this variable 

***** to have any effect. 

*/ 

char * procname="SpecialProcess" ; 

void main (void) 

( 

/* Insert your program here */ 

) 


priority, stack 



— sigfunc 

Synopsis 

Description 


Portability 
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Signal function table 
({include <signal.h> 
extern void {* sigfunc[NSIG] ) (int) ; 

sigfunc is the array of all signal handles. When the raise function 

is called, it looks in the table to see what is installed at the corresponding 

slot in the sigfunc array. Each entry is either a pointer to the 

function to be called when the event occurs or one of two special values: 

SIG—IGN ignore the condition. 

SIG—DFL take the default action. 

There are NSIG elements in the array corresponding to the predefined 
signal values from the file signal . h. 


Symbol 

Value 

Meaning 

SIGABRT 

1 

abnormal termination, abort 

SIGFPE 

2 

floating-point exception 

SIGILL 

3 

illegal instruction 

SIGINT 

4 

interrupt from AmigaDOS, Control-C or Control-D 

SIGSEGV 

5 

segmentation violation (not generated on the 
Amiga) 

SIGTERM 

6 

termination request 


Signals 0, 7, and 8 are reserved for future use (and for compatibility 
with POSIX implementations). 

You should not set elements of this array directly. Use the signal 
function instead. 

UNIX 


See Also raise, signal 
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stack 

Synopsis 

Description 


Portability 

Example 


Minimum program stack size 
((include <dos.h> 
long stack = 8192; 

The global variable stack is used by the startup code to determine 

the minimum stack space necessary to run a program. You must initialize 
the variable at compile time. Setting this variable after the program has 
started does not affect the stack size. 

If the startup code determines that there is not enough stack space to 
satisfy the request, it allocates a temporary stack and runs the program 
on that stack. 

SAS/C 

/* Make sure we have a LOT of stack space to run. */ 

jf include <dos.h> 

long stack = 25000L; 

void main (void) 

( 

/* Insert your program here */ 

} 


See Also 


priority, procname 
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_StdiOv37 Standard I/O window behavior array 

Synopsis # include <dos.h> 

char stdiov37 [ ] = "/AUTO/CLOSE/WAIT"; 

Description When you run a program from the Workbench, the compiler opens a 

standard I/O window in which your program can read from and write to 
stdin, stdout, and stderr. The AmigaDOS Open function is called 

to open this window. Open uses the character string in stdiowin to 

initialize the I/O window. If you are running under Kickstart version 37 

or higher (AmigaDOS 2.0 or higher), the contents of stdiov3 7 is 

appended to stdiowin. The stdiov3 7 variable allows you to 

control the behavior of the standard I/O window. 

The AmigaDOS 2.0 console device supports the following keywords that 
control the behavior of the window: 

AUTO 

specifies not to open the window unless I/O occurs. 

CLOSE 

places a Close gadget on the window. 

WAIT 

specifies not to close the window until you click on the Close gadget or 
type Control-\. 
window 0 xaddress 

specifies to use the window pointed to by the address . Specify the 
address in hexadecimal notation. 

SCREEN name 

opens the standard I/O window on the public screen specified. 

You can also specify BACKDROP, NODRAG, NOBORDER, NOSIZE, 

SIMPLE, and SMART. These keywords control the same attributes as the 
similarly-named Intuition window flags. 

The default string specifies that the window should open only if your 
program actually reads or writes data to it; that the window should have 
a Close gadget; and that the window should wait for the user to press the 
Close gadget or type an end-of-file character before closing the window. 
For more information on console specifications, refer to the information 
about AmigaDOS CON: device input and output in The AmigaDOS 
Manual, 3rd Edition (Commodore-Amiga, Inc. 1991). 

To change the window behavior, include a line similar to the line 
shown in the Synopsis above in any C source file in your project. Declare 
this variable external to any function, and be sure to initialize the 
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StdiOV37 Standard I/O window behavior array 

( continued ) 

variable. Any changes made to this external variable after your program 
starts do not affect the window. 

For more information on managing the standard I/O window, refer to 
Chapter 9, “Running Your Program from the Workbench,” in SAS/C 
Development System User’s Guide, Volume 1. 

Portability SAS/C 

Example /* Define a window that opens only if your program */ 

/* reads or writes data to it and that closes */ 

/* automatically when the program ends. */ 

Hinclude <dos.h> 

char stdiov37[l = "/AUTO"; 


See Also stdiowin 
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_stdiowin 

Synopsis 

Description 


Portability 

Examples 


See Also 


Standard I/O window attributes array 
iinclude <dos.h> 

char stdiowin!) = "CON: 10/10/320/80/" ; 

When you run a program from the Workbench, the compiler opens a 
standard I/O window in which your program can read from and write to 
stdin, stdout, and stderr. The AmigaDOS Open function is called 

to open this window. Open uses the character string in stdiowin to 

initialize the I/O window. 

The default specification opens a console window starting at location 
(10,10) that is 320 pixels wide and 80 pixels high. For more information 
on console specifications, refer to The AmigaDOS Manual, 3rd Edition 
(Commodore-Amiga, Inc. 1991). 

You can control the attributes of this window using the stdiowin 

variable. To change the window attributes, include a line similar to the 
line shown in the Synopsis above in any C source file in your project. 
Declare this variable external to any function, and be sure to statically 
initialize the variable. Any changes made to this external variable after 
your program starts do not affect the window. 

Note: The replacement string for stdiowin must end in a slash 

(/), or it must end with a window title. Refer to the examples later in 
this section for specific examples. 

For more information on managing the standard I/O window, refer to 
Chapter 9, “Running Your Program from the Workbench,” in SAS/C 
Development System User’s Guide, Volume 1. 

SAS/C 

/* Make the window 600 pixels wide and 100 pixels */ 

/* tall. Add a window title of "My Window." */ 

char stdiowin[ ]= "CON: 10/10/600/100 /My Window"; 


/* Make the window 500 pixels wide and 200 pixels */ 
/* tall. Do not include a window title. */ 

char stdiowin! ]="C0N: 10/10/500/200/" ; 

stdiov37 
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STKNEED 

Synopsis 

Description 


Portability 

Example 


See Also 


Minimum function stack size 
jfinclude <dos.h> 
long STKNEED = 400 ; 

The variable STKNEED specifies the minimum amount of stack needed 

by each function in your program. 

If you declare a function with the stackext keyword or compile it 

with the stackext option, the compiler generates extra code at the start 
of the function. This extra code compares the amount of stack available 

with the amount specified in STKNEED and, if enough stack is not 

available, allocates a new stack extent whose size is specified in 
stack. 

The default value of STKNEED is 400. The default value of 

stack is 8192 bytes. If a system interrupt occurs, it will use your 

stack; therefore, you must keep at least 400 bytes of stack free at all 
times. 

If your functions require additional space, declare STKNEED in your 

code and statically initialize it to the amount you require. If necessary, 

you can change the value of STKNEED in your program code; if the 

current stack does not meet the new STKNEED value, a new one is 

allocated the next time you call a function declared with the 
stackext keyword or compiled with the stackext option. 

For more information on managing stack space, refer to Chapter 11, 
Using SAS/C Extensions to the C and C+ + Languages,” in SAS/C 
Development System User’s Guide, Volume 1. 

SAS/C 

/* Make sure each function has enough stack space. */ 

Ifinclude <dos.h> 

long STKNEED = 600; 

void main (void) 

/* Insert your program here */ 

) 
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SysBase Base of the Exec library 

Synopsis jfdefine USE_SYSBASE 1 

jfinclude <proto/exec.h> 

Description This external location is used to point to the base of the Amiga operating 
system library, Exec. Memory location 4 always contains a pointer to the 
Exec library’s structure, and it can be used instead of SysBase. 
However, on machines with 68020 or higher processors, it is faster to 
use SysBase rather than read location 4 repeatedly. 

If you use SysBase, the standard startup code for programs and 
libraries initializes SysBase for you. If you do not link with one of the 
startup modules supplied by the SAS/C Development System, you must 
initialize SysBase in your code. 

SysBase is declared in the file proto/exec . h. To use SysBase 
rather than location 4 in your Exec calls, you should define the 

preprocessor symbol USE_SYSBASE before including 

proto/exec . h. 

You cannot obtain the address of the Exec library by using 
OpenLibrary, since OpenLibrary is itself an Exec function. 
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sys_errlist Errno text strings 


Synopsis § include <errno.h> 


extern char * sys_errlist [ ] ; 

Description The external array of strings sys_errlist provides the text 

message that corresponds to a given errno value. The value of errno is 
used as a direct index to this table. You should avoid accessing this table 
directly to print errors. Instead, use the perror or strerror 
functions. 

You may want to substitute your own table for internationalization of 

your program. The external integer sys_nerr indicates the number 

of entries in sys_errlist. 

If you change sys_err list dynamically in your program, as 

shown in the example below, the changes are only in effect for that 
program while it is running. To change the messages permanently for all 
programs, modify syserr.c in the source directory, compile it, and use 
the OML to replace it in all nonmath libraries that you plan to use. As an 
alternative, you can compile the syserr.c file and link it with all 
programs in which you want modified messages. 

In Version 5.10 and earlier, this variable was named sys_errlist. 

Portability SAS/C 

Example /* Print error message number 1 with perror, change the */ 

/* message to all capitals, and then print the */ 

/* message again. */ 


({include <errno.h> 


void main (void) 

( 

const char *x = "Test Message"; 
errno = 1 ; 
perror ( x) ; 

— sys_errlist [ errno] = "USER IS NOT OWNER"; 
perror(x) ; 

} 

See Also perror, strerror, sys_nerr 
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_sys_nerr 

Synopsis 

Description 

Portability 

Example 


Number of entries in sys_errlist 

((include <errno.h> 
extern int sys_nerr; 

The external integer sys_nerr indicates the number of entries in the 

sys_errlist array. 

In Version 5.10 and earlier, this variable was named sys_nerr. 
SAS/C 

/* 

* Print all possible errors from the sys_errlist array 

*/ 

((include <errno.h> 

void main (void) 

( 

int i ; 

for ( i = 0; i <= sys_nerr; i++) 

i 

printf ( "Message %d = Ks \n" , i , strerror ( i ) ) ; 

] 

) 


See Also perror, strerror, sys_errlist 
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—TZ 

Synopsis 

Description 


Portability 

Example 


See Also 


Default time zone name 
iinclude <time.h> 
extern char *_TZ; 

This variable is the default time zone that is used if there is no 
environment variable TZ set on the Amiga. If you set it, you must make 
sure that the memory for it is not freed until you reset it. If _TZ is not 
set to any value, CST6 is used instead. 

The value of the variable _TZ is used to set other time zone variables, 

including tzstn, tzdtn, and daylight. The first three 

characters are taken as the name. The remaining characters are taken as 
the ASCII representation of the number of hours offset from Greenwich 
Mean Time (GMT) for the time zone. 

SAS/C 

/* 

* Print out the default time zone and then set it to be EST. 

*/ 

H include <time.h> 
jfinclude <stdio.h> 

void main(void) 

{ 

printf ( "Default Time Zone = Xs\n", _TZ); 

_TZ = "EST5" ; 

) 
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ufbs 

Synopsis 


Description 


Portability 


Array of open level 1 file handles 

jjinclude <ios1.h> 

extern struct UFB * ufbs; 

ufbs is used to track all open level 1 file handles. ufbs is the 

pointer to the beginning of the linked list containing the file handles. If 
ufbs is equal to NULL, then there are no open level 1 files. 

The open or creat function returns the entry number of the file 
handle in the linked list. For example, if the open function returns 5, the 
file handle is the fifth entry of the linked list. 

It is not recommended that you access this linked list directly. The 
chkuf b function is provided to translate an index into the appropriate 
UFB structure. The UFB structure actually consists of four members: 

struct UFB 
1 


struct UFB *ufbnxt; 

/* 

next ufb */ 

int ufbflg; 

/* 

flags */ 

long ufbfh; 

/* 

file handle */ 

char *ufbfn; 

/* 

file name */ 


The ufbf lg field consists of bits as defined here: 


UFB—RA indicates that the file may be read from. 

UFB—WA indicates that the file may be written to. 

UFB_NC indicates that the file handle should not be closed on 
exit. 


UFB—APP indicates that the file may be appended to on write. 
UFB_XLAT indicates file translation mode. 

UFB—TEMP indicates the file is a temporary file. 


In Version 5.10 and earlier, the linked list ufbs was an array 

named _uf bs. 


SAS/C 


See Also chkuf b, nufbs, open 
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_WBenchMsg Workbench startup message 
Synopsis jf include <dos.h> 

struct WBStartup *_WBenchMsg; 

Description —WBenchHsg contains the arguments passed to your program from the 
Workbench. The value is passed to your program as argv [ 0 ] if it is 
invoked from the Workbench. 

For more information about handling arguments passed to your 
program from the Workbench, refer to Chapter 9, “Running Your 
Program from the Workbench,” in SAS/C Development System User’s 
Guide, Volume 1. 

In Version 5.10, this variable was named WBenchMsg. 

Portability AmigaDOS 
See Also main 
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C Library Reference 


This chapter describes the library functions provided with the SAS/C 
software. 

The functions are described in alphabetical order. Each function 
description includes the following sections (if applicable): 


Synopsis shows the declaration for the function, including any 

header files that must be included in the calling routine. 

Note: The keyword const is used in the declarations of 
many of the variables referenced by the library functions. 
This keyword defines variables as read only, and its use in 
the libraries ensures that the library functions do not 
change the values of these variables. Do not use the 
keyword const in variable declarations unless you want to 
prevent your program from changing the value of that 
variable. The compiler issues an error message if you try to 
modify the contents of a variable declared with the keyword 
const. 


Description describes what the function does and contains all the 
information you need to use the function. This section 
identifies all functions that are not available if you define 

the strict ansi preprocessor symbol. For more 

information, see the following section, “The 
_STRICT_ANSI Symbol.” 

Portability describes the systems or languages with which the function 
is compatible. A library function’s portability falls into one 
of these categories: 


AmigaDOS indicates the function can be used only on 
machines running AmigaDOS. 

ANSI indicates the function is compatible with the 
definition in the ANSI Standard for C. 


SAS/C indicates the function is in the SAS/C 

Development System library. SAS/C functions 
are available only when using the SAS/C 
libraries and may or may not be equivalent to 
functions in libraries from other vendors. 



OLD indicates the function was defined in earlier 
versions of the SAS/C Compiler and can still 
be used, although the newer ANSI and 
AmigaDOS functions are now preferred. 

UNIX indicates the function is compatible with 

AT&T’s UNIX System V or BSD 4.x UNIX. 

XENIX indicates the function is compatible with 
Microsoft’s XENIX. 

Returns describes any values that the function returns. If the 
function does not return anything, this section is not 
included for that function. 

Example contains sample code showing how to use the function. If 
the function is OLD, an example is not included. 

See Also refers you to the descriptions of data names and other 
functions that contain related information. 


The _STRICT_ANSI Symbol 

The ANSI Standard for C requires that certain compiler header files must 
be provided and that these compiler header files and the libraries define 
certain symbols, macros, and functions. The SAS/C Development System 
headers and libraries define all of the required ANSI symbols. They also 
define many other symbols that are not required by the ANSI Standard. 

To be completely ANSI-compliant, an implementation must not define 
any non-ANSI symbols in an ANSI header file unless the symbols begin 
with an underscore followed by a capital letter or an underscore followed 
by another underscore. 

If you define the preprocessor symbol _STRICT_ANSI, the SAS/C 
Development System headers do not define any symbols, macros, or 
functions that violate the ANSI Standard naming conventions. You can 
use a #def ine statement to define the _STRICT_ANSI symbol, or you 
can define it on the command line. If you define the _STRICT_ANSI 
symbol, the compiler does not include the prototypes or # define 
statements for some library functions and macros. The descriptions in 
this chapter identify which functions and macros are affected by the 
STRICT ANSI preprocessor symbol. 
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Function Categories 

The following lists contain the names, descriptions, and portability 
classifications of all of the functions described in this manual. These 
functions are grouped by category such as string functions or I/O 
functions. Within each category, functions that perform similar tasks are 
listed together. For example, stpchrn and strrchr both perform the 
same function, however, stpchrn is an OLD function and strrchr is 
an ANSI function. Some functions may be listed twice. For example, the 
ctime function is listed under “Conversion Functions” and under “Time 
Functions.” 


Character-Type 
Macros and 
Functions 

Function 

Portability 

Description 

isalnum 

ANSI 

check if a character is alphanumeric 


isalpha 

ANSI 

check if a character is alphabetic 


isascii 

SAS/C 

check if a character is an ASCII character 


iscntrl 

ANSI 

check if a character is a control character 


i s c s ym 

SAS/C 

check if a character is a C symbol 
character 


iscsymf 

SAS/C 

check if a character is a C symbol lead 
character 


isdigit 

ANSI 

check if a character is a decimal digit 
(0-9) 


Isgraph 

ANSI 

check if a character is a graphic character 


islower 

ANSI 

check if a character is lowercase 


isprint 

ANSI 

check if a character is printable 


ispunct 

ANSI 

check if a character is a punctuation 
character 


isspace 

ANSI 

check if a character is a space 


isupper 

ANSI 

check if a character is uppercase 


isxdigit 

ANSI 

check if a character is a hex character 
(0-9, A-F, a-f) 


( continued ) 
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String Functions 


Function 

Portability 

Description 

toascii 

SAS/C 

convert a character to an ASCII character 

tolower 

ANSI 

convert a character to lowercase 

toupper 

ANSI 

convert a character to uppercase 

See also “Memory Manipulation Functions,” later in this section. 

Function 

Portability 

Description 

astcsma 

AmigaDOS 

AmigaDOS string pattern match 
(anchored) 

scdir 

OLD 

Return the name of the next file matching 
pattern 

stcpm 

SAS/C 

unanchored pattern match 

stcpma 

SAS/C 

anchored pattern match 

stcsma 

AmigaDOS 

UNIX string pattern match (anchored) 

stccpy 

UNIX 

copy one string to another 

stpcpy 

SAS/C 

copy one string to another 

strcpy 

ANSI 

copy one string to another 

strncpy 

ANSI 

copy a string, length limited 

stcis 

SAS/C 

count the number of string characters in 
the set 

stcisn 

SAS/C 

count the number of string characters not 
in the set 

strcspn 

ANSI 

count the number of string characters not 
in the set 

stolen 

OLD 

measure the length of a string 

strlen 

ANSI 

measure the length of a string 

strspn 

ANSI 

count the number of string characters in 
the set 

stpbrk 

OLD 

find a break character in a string 

( continued ) 
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Function 

Portability 

Description 

stpchr 

OLD 

find a character in a string 

strchr 

ANSI 

find a character in a string 

stpchrn 

OLD 

find a character not in a string 

strrchr 

ANSI 

find a character not in a string 

strpbrk 

ANSI 

find a break character in a string 

strcat 

ANSI 

concatenate strings 

strncat 

ANSI 

concatenate strings, length limited 

strcmp 

ANSI 

compare strings, case sensitive 

strcmpi 

OLD 

compare strings, case insensitive 

str icmp 

SAS/C 

compare strings, case insensitive 

strncmp 

ANSI 

compare strings, length limited 

strnicmp 

SAS/C 

compare strings, case insensitive, length 
limited 

strnset 

XENIX 

set a string to a value, length limited 

strset 

XENIX 

set a string to a value 

strtok 

ANSI 

get a token 

stcarg 

SAS/C 

get an argument 

stpsym 

SAS/C 

get the next symbol from a string 

stptok 

SAS/C 

get the next token from a string 

stpblk 

SAS/C 

skip blanks 

strbpl 

SAS/C 

build a string-pointer list 

strdup 

XENIX 

duplicate a string 

strins 

SAS/C 

insert a string 

strrev 

XENIX 

reverse a character string 

strmid 

SAS/C 

return a substring from a string 

strstr 

ANSI 

find a substring inside of a string 
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Conversion 

Functions 

Function 

Portability 

Description 

atof 

ANSI 

convert an ASCII string to a floating- 
point number 


atoi 

ANSI 

convert an ASCII string to an integer 


atol 

ANSI 

convert an ASCII string to a long integer 


stcd_i 

SAS/C 

convert a decimal string to an integer 


stcd_l 

SAS/C 

convert a decimal string to a long integer 


ecvt 

UNIX 

convert a double-precision floating-point 
number to a string 


f cvt 

UNIX 

convert a floating-point number to a 
string 


gcvt 

UNIX 

convert a floating-point number to a 
string 


stch_i 

SAS/C 

convert a hexadecimal string to an 
integer 


stch_l 

SAS/C 

convert a hexadecimal string to a long 
integer 


stci_d 

SAS/C 

convert an integer to a decimal string 


stci_h 

SAS/C 

convert an integer to a hexadecimal 
string 


s t c i_o 

SAS/C 

convert an integer to an octal string 


stcl_d 

SAS/C 

convert a long integer to a decimal string 


stcl_h 

SAS/C 

convert a long integer to a hexadecimal 
string 


stcl_o 

SAS/C 

convert a long integer to an octal string 


stco_i 

SAS/C 

convert an octal string to an integer 


stco_l 

SAS/C 

convert an octal string to a long integer 


stcu_d 

SAS/C 

convert an unsigned integer to a decimal 
string 


stcul_d 

SAS/C 

convert an unsigned long integer to a 
decimal string 


( continued ) 
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Function 

Portability 

Description 

str lwr 

XENIX 

convert a string to lowercase 

strtod 

ANSI 

convert a string to a double-precision 
floating-point number 

strtol 

ANSI 

convert a string to a long integer 

strtoul 

ANSI 

convert a string to an unsigned long 
integer 

toascii 

SAS/C 

convert a character to an ASCII string 

tolower 

ANSI 

convert a character to lowercase 

toupper 

ANSI 

convert a character to uppercase 

mbstowcs 

ANSI 

convert a multibyte string to a wide- 
character string 

wcstombs 

ANSI 

convert a wide-character string to a 
multibyte string 

stpdate 

SAS/C 

convert a date array to a string 

stptime 

SAS/C 

convert a time array to a string 

mktime 

ANSI 

convert a broken down time to a 
time_t value 

timecvt 

AmigaDOS 

convert a time_t value to an AmigaDOS 
DateStamp 

ct ime 

ANSI 

convert a t ime_t value to an ASCII 
string 

utpack 

SAS/C 

pack UNIX time 

utunpk 

SAS/C 

unpack UNIX time 



116 Chapter 7 


Mathematical Function 

Mai'I'AC *1 n 

Portability 

Description 

mdcros afiu 

Functions abs 

ANSI 

absolute value 

acos 

ANSI 

arccosine function 

asin 

ANSI 

arcsine function 

atan 

ANSI 

arctangent function 

atan2 

ANSI 

arctangent of x/y 

ceil 

ANSI 

get floating-point limits 

cos 

ANSI 

cosine function 

cosh 

ANSI 

hyperbolic cosine function 

cot 

UNIX 

cotangent function 

di v 

ANSI 

compute the quotient and the remainder 

exp 

ANSI 

exponential function 

f abs 

ANSI 

floating-point or double-precision floating- 



point absolute value 

floor 

ANSI 

get the floor of a real number 

fmod 

ANSI 

floating-point modulus operations 

f rexp 

ANSI 

split floating-point value 

iabs 

SAS/C 

integer absolute value 

labs 

ANSI 

long integer absolute value 

ldexp 

ANSI 

combine floating-point value 

ldi v 

ANSI 

return the long integer quotient and the 



remainder 

log 

ANSI 

natural logarithm function 

log 1 0 

ANSI 

base 10 logarithm function 

max 

UNIX 

compute the maximum of two values 

min 

UNIX 

compute the minimum of two values 

modf 

ANSI 

split a floating-point value 

pow 

ANSI 

raise a number to a power 

pow2 

SAS/C 

raise 2 to a power 


( continued ) 
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Function 

Portability 

Description 


sin 

ANSI 

sine function 


s inh 

ANSI 

hyperbolic sine function 


sqrt 

ANSI 

square root function 


tan 

ANSI 

tangent function 


tanh 

ANSI 

hyperbolic tangent function 

Varying-Length 

Function 

Portability 

Description 

Argument List 
Macros 

va_arg 

ANSI 

get an argument from a varying-length 
argument list 


va_end 

ANSI 

end varying-length argument list 
processing 


va_start 

ANSI 

begin varying-length argument list 
processing 

General Utility 

Function 

Portability 

Description 

Macros and 
Functions 

emit 

SAS/C 

emit 680x0 instruction word 


getreg 

SAS/C 

get 680x0-specific registers 


putreg 

SAS/C 

set up 680x0-specific registers 


geta4 

OLD 

establish addressability to the global data 




area 


isatty 

UNIX 

test a file descriptor for a terminal device 


ovlyMgr 

AmigaDOS 

overlay manager call point 


of f setof 

ANSI 

get the byte offset of a structure member 
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Sorting Functions 


Random-Number 

Generation 

Functions 


Function 

Portability 

Description 

bsearch 

ANSI 

perform a binary search 

dqsort 

SAS/C 

sort an array of double-precision floating- 
point numbers 

f qsort 

SAS/C 

sort an array of floating-point numbers 

lqsort 

SAS/C 

sort an array of long integers 

qsort 

ANSI 

sort a data array 

sqsort 

SAS/C 

sort an array of short integers 

strsrt 

SAS/C 

sort a string-pointer list 

tqsort 

SAS/C 

sort an array of text pointers 

Function 

Portability 

Description 

drand48 

UNIX 

generate a random double-precision 
floating-point number (internal seed) 

erand48 

UNIX 

generate a random double-precision 
floating-point number (external seed) 

jrand48 

UNIX 

generate a random long integer (external 
seed) 

lcong48 

UNIX 

set linear congruence parameters 

lrand48 

UNIX 

generate a random positive long integer 
(internal seed) 

mrand48 

UNIX 

generate a random long integer (internal 
seed) 

nrand48 

UNIX 

generate a random positive long integer 
(external seed) 

rand 

ANSI 

generate a random number 

seed48 

UNIX 

set all 48 bits of an internal seed 

srand 

ANSI 

set a seed for the rand function 

srand48 

UNIX 

set high 32 bits of an internal seed 



C Library Reference 119 


Program Control 

Function 

Portability 

Description 

Functions 

abort 

ANSI 

abort the current process 


atexit 

ANSI 

set an exit trap 


autoopenf ail 

AmigaDOS 

terminate the program if 
OpenLibrary fails 


chkabort 

AmigaDOS 

check for a break character 


Chk__Abort 

AmigaDOS 

check for a break character 


CXBRK 

AmigaDOS 

print message and exit for Control-C 
processing 


exit 

ANSI 

terminate program execution 


exit 

SAS/C 

terminate program execution with no 
clean-up 


onexit 

OLD 

set an exit trap 


XCEXIT 

SAS/C 

terminate the program 


f orkl 

SAS/C 

create a child process with an 
argument list 


f orkv 

SAS/C 

create a child process with an 
argument vector 


long jmp 

ANSI 

perform a long jump 


set jmp 

ANSI 

set long jump parameters 


onbreak 

AmigaDOS 

plant a break trap 


wait 

SAS/C 

wait for a single child process to 
complete 


waitm 

SAS/C 

wait for multiple child processes to 
complete 


raise 

ANSI 

generate a signal 


signal 

ANSI 

establish event traps 
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Memory 

Allocation 

Functions 


Memory 

Manipulation 

Functions 


Function 

Portability 

Description 

bldmem 

OLD 

build a memory pool of a specified size 

rstmem 

OLD 

reset a memory pool 

s i zraem 

SAS/C 

get the memory pool size 

chkml 

SAS/C 

check for the largest memory block 

getmem 

OLD 

get a memory block (short) 

getml 

OLD 

get a memory block (long) 

halloc 

SAS/C 

allocate a huge memory block 

lsbrk 

OLD 

allocate memory 

sbrk 

OLD 

allocate memory (unsigned) 

calloc 

ANSI 

allocate and clear memory 

malloc 

ANSI 

allocate memory 

realloc 

ANSI 

reallocate memory 

free 

ANSI 

free memory 

—MemCleanup 

AmigaDOS 

deallocate all allocated memory 

rbrk 

OLD 

release memory 

r lsmem 

OLD 

release a memory block 

r lsml 

OLD 

release a memory block 

Function 

Portability 

Description 

memchr 

ANSI 

find a character in a memory block 

memcmp 

ANSI 

compare two memory blocks 

memccpy 

SAS/C 

copy a memory block 

memcpy 

ANSI 

copy a memory block 

memmove 

ANSI 

copy bytes in memory 


( continued ) 
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Function 

Portability 

Description 

meraset 

ANSI 

set a memory block to a value 

movmem 

UNIX 

move a memory block 

repmem 

SAS/C 

replicate values through a block 

setmem 

UNIX 

set a memory block to a value 

swmem 

UNIX 

swap two memory blocks 


Diagnostic 
Control Functions 

Function 

Portability 

Description 

assert 

ANSI 

assert program validity 


except 

SAS/C 

call the math error handler 


matherr 

UNIX 

math error handler 


perror 

ANSI 

print an error message 


poserr 

AmigaDOS 

print an AmigaDOS error message 


strerror 

ANSI 

print the text for a given error number 

Time Functions 

Function 

Portability 

Description 


asct ime 

ANSI 

generate an ASCII time string 


clock 

ANSI 

measure program processor time 


datecmp 

AmigaDOS 

compare two AmigaDOS dates 


dif f time 

ANSI 

compute the difference between two 
time_t values 


gmtime 

ANSI 

unpack Greenwich Mean Time (GMT) 


localtime 

ANSI 

unpack local time 


mkt ime 

ANSI 

convert a broken down time to a time_t 
value 


str f time 

ANSI 

format a time string 


( continued ) 
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Function 

Portability 

Description 

time 

ANSI 

get the system time in seconds 

ct ime 

ANSI 

convert a time_t value to an ASCII 
string 

t imecvt 

AmigaDOS 

convert a time_t value to an AmigaDOS 
DateStamp 

timer 

AmigaDOS 

get the system clock with microseconds 

tzset 

XENIX 

set the time zone variables 

utpack 

SAS/C 

pack UNIX time 

utunpk 

SAS/C 

unpack UNIX time 


I/O Functions 


Standard I/O Functions 


Function 

Portability 

Description 

getch 

SAS/C 

get a character from stdin immediately 

getchar 

ANSI 

get a character from stdin 

f getchar 

XENIX 

get a character from stdin 

f putchar 

XENIX 

put a character to stdout 

putchar 

ANSI 

put a character to stdout 

gets 

ANSI 

get a string from stdin 

puts 

ANSI 

put a string to stdout 

printf 

ANSI 

formatted print to stdout 

scanf 

ANSI 

formatted input conversions 

vpr intf 

ANSI 

formatted write of a varying-length 
argument list to stdout 
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Character I/O Functions 


Function 

Portability 

Description 

f getc 

ANSI 

get a character from a file 

getc 

ANSI 

get a character from a file 

ungetc 

ANSI 

push an input character back 

getch 

SAS/C 

get a character from stdin immediately 

getchar 

ANSI 

get a character from stdin 

f getchar 

XENIX 

get a character from stdin 

f putc 

ANSI 

put a character to a level 2 file 

f putchar 

XENIX 

put a character to stdout 

putc 

ANSI 

put a character to a level 2 file 

putchar 

ANSI 

put a character to stdout 

String I/O Functions 


Function 

Portability 

Description 

f gets 

ANSI 

get a string from a level 2 file 

gets 

ANSI 

get a string from stdin 

f puts 

ANSI 

put a string to a level 2 file 

puts 

ANSI 

put a string to stdout 

Block I/O Functions 


Function 

Portability 

Description 

—dread 

OLD 

read an AmigaDOS file 

_dwr ite 

OLD 

write to an AmigaDOS file 

f read 

ANSI 

read and write blocks 

f write 

ANSI 

write blocks to a level 2 file 

read 

UNIX 

read from a level 1 file 

write 

UNIX 

write to level 1 file 



Formatted I/O Functions 


Function 

Portability 

Description 

f printf 

ANSI 

formatted print 

printf 

ANSI 

formatted print to stdout 

spr intf 

ANSI 

formatted print to a string 

f scanf 

ANSI 

formatted input conversions 

scanf 

ANSI 

formatted input conversions 

sscanf 

ANSI 

formatted input conversions 

vf printf 

ANSI 

formatted write of a varying-length 
argument list to a file 

vpr intf 

ANSI 

formatted write of a varying-length 
argument list to stdout 

vsprintf 

ANSI 

formatted write of a varying-length 
argument list to a string 


Error Handling Functions 

Function Portability Description 

ANSI check for a level 2 end-of-file 

ANSI check for a level 2 error 

ANSI clear a level 2 I/O error flag 

UNIX clear a level 2 I/O error flag 


f eof 
f error 
clearerr 


clrerr 
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File Control Functions 

Function Portability Description 

close 

UNIX 

close a level 1 file 

_ dclose 

OLD 

close an AmigaDOS file 

f close 

ANSI 

close a level 2 file 

f closeall 

XENIX 

close all level 2 files 

tmpnam 

ANSI 

create a temporary filename 

creat 

UNIX 

create a level 1 file 

_dcreat 

OLD 

create an AmigaDOS file 

—dcreatx 

OLD 

create a new AmigaDOS file 

f dopen 

UNIX 

attach a level 1 file to level 2 

f ileno 

UNIX 

get the file number for a level 2 file 

fmode 

SAS/C 

change the mode of a level 2 file 

iomode 

SAS/C 

change the mode of a level 1 file 

open 

UNIX 

open a level 1 file 

_dopen 

OLD 

open an AmigaDOS file 

f open 

ANSI 

open a level 2 file 

tmpf i le 

ANSI 

open a temporary file stream 

f reopen 

ANSI 

reopen a level 2 file 

f flush 

ANSI 

flush a level 2 output buffer 

f lushall 

XENIX 

flush all level 2 output buffers 

mkstemp 

UNIX 

Make a unique filename and open the file 

mktemp 

UNIX 

Make a unique filename 

setbuf 

ANSI 

set the buffer mode for a level 2 file 

setnbf 

UNIX 

turn off I/O buffering for a level 2 file 

setvbuf 

ANSI 

set the variable buffer for a level 2 file 
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File Management 
Functions 


File Positioning Functions 


Function 

Portability 

Description 

_dseek 

OLD 

reposition an AmigaDOS file 

f seek 

ANSI 

set a level 2 file position 

lseek 

UNIX 

set a level 1 file position 

f getpos 

ANSI 

get the current file position 

f setpos 

ANSI 

reposition a file 

f tell 

ANSI 

get a level 2 file position 

tell 

UNIX 

get a level 1 file position 

rewind 

ANSI 

reset a level 2 file position to its first byte 

Function 

Portability 

Description 

access 

UNIX 

check file accessibility 

chkuf b 

SAS/C 

check a level 1 file handle 

f ileno 

UNIX 

get the file number for a level 2 file 

chmod 

UNIX 

change a file’s protection mode 

fmode 

SAS/C 

change the mode of a level 2 file 

iomode 

SAS/C 

change the mode of a level 1 file 

f stat 

UNIX 

get file status 

getf a 

AmigaDOS 

get the file attribute 

getf t 

AmigaDOS 

get the file time 

stat 

UNIX 

get information on a file 

stcgf e 

SAS/C 

get the filename extension 

stcgf n 

SAS/C 

get a filename from a path 

stcgf p 

SAS/C 

get a file path 

strmf e 

SAS/C 

make a filename with an extension 


(i continued ) 
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System Interface 
Functions 


Function 

Portability 

Description 

strmf n 

SAS/C 

make a filename from components 

strmf p 

SAS/C 

make a filename from path or node 

strsf n 

SAS/C 

split the filename 

unlink 

UNIX 

remove a file 

remove 

ANSI 

remove a file 

rename 

ANSI 

rename a file 

setbuf 

ANSI 

set the buffer mode for a level 2 file 

setnbf 

UNIX 

turn off I/O buffering for a level 2 file 

setvbuf 

ANSI 

set the buffer mode for a level 2 file 

Function 

Portability 

Description 

argopt 

SAS/C 

get options from an argument list 

chgclk 

AmigaDOS 

change the system clock 

dos_packet 

OLD 

send AmigaDOS output packet 

getclk 

AmigaDOS 

get or change the system clock 

getasn 

AmigaDOS 

get assigned device 

getdf s 

AmigaDOS 

get disk free space 

getenv 

ANSI 

get environment variable 

putenv 

UNIX 

put a string into the environment 

rawcon 

AmigaDOS 

set or unset raw console input 

stackavail 

SAS/C 

get the current available stack size 

stacksize 

SAS/C 

get the current stack size 

stackused 

SAS/C 

get the amount of stack in use 

system 

ANSI 

call the system command processor 
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Directory 

Functions 

Function 

Portability 

Description 

chdir 

UNIX 

change the current directory 


closedir 

UNIX 

terminate the directory operation 


df ind 

AmigaDOS 

find a directory entry 


dnext 

AmigaDOS 

find the next directory entry 


f indpath 

AmigaDOS 

locate a file in the current path 


getcd 

AmigaDOS 

get the current directory 


getcwd 

UNIX 

get the current working directory 


getf nl 

SAS/C 

get a filename list 


getpath 

AmigaDOS 

get the path for a specific directory or file 


mkdir 

UNIX 

make a new directory 


opendir 

UNIX 

initiate a directory operation 


readdir 

UNIX 

read a directory element 


rmdir 

UNIX 

remove a directory 


seekdir 

UNIX 

reposition a directory operation 


rewinddir 

UNIX 

reset to the start of the directory 


telldir 

UNIX 

get the directory position 

Localization 

Functions 

Function 

Portability 

Description 

localeconv 

ANSI 

return information on locale formatting 
conventions 



readlocale 

SAS/C 

read and initialize a new locale 


setlocale 

ANSI 

set locale information for a program 


strcoll 

ANSI 

compare strings based on locale 


strxf rm 

ANSI 

transform a string 
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Multibyte 

Function 

Portability 

Description 

Character 

Functions 

mblen 

ANSI 

determine the length of a multibyte 
character 


mbstowcs 

ANSI 

convert a multibyte string to a wide- 
character string 


mbtowc 

ANSI 

map a multibyte character to a wide 
character 


wcstombs 

ANSI 

convert a wide-character string to a 
multibyte string 


wctomb 

ANSI 

map a wide character to a multibyte 
character 

Screen Control 

Function 

Portability 

Description 

Functions 

scr_beep 

OLD 

call Intuition DisplayBeep 


scr_bs 

OLD 

move the cursor left one position 


scr_cdelete 

OLD 

delete the character under the cursor 


scr_cinsert 

OLD 

insert a blank character at the cursor 


scr_clear 

OLD 

clear the window 


scr_cr 

OLD 

cause a carriage return 


scr_curs 

OLD 

move the cursor to specified line and 
column 


scr_cursrt 

OLD 

move the cursor right one character 


scr_cur sup 

OLD 

move the cursor up one line 


scr_eol 

OLD 

erase from the cursor to the end-of-line 


scr_home 

OLD 

move the cursor to the upper left 


scr_ldelete 

OLD 

delete the line at the cursor position 


scr_lf 

OLD 

move the cursor down one line 


scr_linsert 

OLD 

insert a blank line at the cursor 


scr_tab 

OLD 

move the cursor right one tab stop 
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Functions the Function 
User Can 

Portability 

Description 




Replace But Not - CXFERR 

SAS/C 

low-level floating-point error 

Call _cxovf 

SAS/C 

default stack-overflow handler 

Built-in Functions Function 

Portability 

Description 

strcpy 

ANSI 

copy one string to another 

strlen 

ANSI 

measure the length of a string 

strcmp 

ANSI 

compare strings 

raemcmp 

ANSI 

compare two memory blocks 

memcpy 

ANSI 

copy a memory block 

memset 

ANSI 

set a memory block to a value 

abs 

ANSI 

absolute value 

max 

UNIX 

compute the maximum of two values 

min 

UNIX 

compute the miminum of two values 

emit 

SAS/C 

emit 680x0 instruction word 

getreg 

SAS/C 

get 680x0-specific registers 

putreg 

SAS/C 

set up 680x0-specific registers 

getaH 

OLD 

establish addressability to the global data 


area 
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abort Abort the current process 
Synopsis § include <stdlib.h> 
void abort( void) ; 

Description This function aborts the current process and returns a completion code of 
3 to the parent process. Also, the message Abnormal program 
termination is sent to stderr. Level 2 I/O buffers are flushed. 

From within a shared library, you must not call any library functions 
that terminate your program. For example, you cannot call exit, 

exit, or abort from a shared library. You also cannot use set jmp 

and long jmp to jump across a call from the program into the library. 

Portability ANSI 

Example /* Do your own memory allocation */ 

finclude <stdio.h> 

((include <stdlib.h> 

void *gmem(size_t size) 

( 

void *p; 

if ( (p=malloc(size) )==NULL) 

( 

abort( ) ; 

) 

return(p) ; 


void main(void) 

i 

void *p; 

p = gmem( 4096) ; 
it (p) 

( 

free(p) ; 


) 


) 
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abort Abort the current process 
(continued) 

See Also exit, exit, raise, _XCEXIT 
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abs 

Synopsis 


Description 


Portability 

Returns 


Absolute value 

((include <stdlib.h> 

ax = abs(x) ; 

type x; 
type ax; 

This macro computes the absolute value of the various numeric data 
types. It accepts any data type as its argument and generates in-line code 
to perform the conversion. The definition is 

((define abs(x) ( (x)<0?-(x) : (x) ) 

To minimize code size, you can use the fabs, iabs, or labs function 
instead. Choose the function that corresponds to the data type being 
converted. 

ANSI 

The return value is the absolute value of the argument. 


See Also 


fabs, iabs, labs 
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access 

Synopsis 


Description 


Portability 

Returns 


Check file accessibility 

((include <stdio.h> 

ret = access(name,mode) ; 

int ret; /* return code */ 

const char *name; /* file name */ 
int mode; /* access mode */ 

This function checks if a file is accessible in the way specified by the 
mode parameter. The following table shows the modes, which follow the 
UNIX format, accepted by this function. 


Name 

Value 

Meaning 

R OK 

4 

check if the file is readable 

W_OK 

2 

check if the file is writable 

X OK 

1 

check if the file is executable 

F OK 

0 

check if the file exists 


You can simultaneously check for more than one attribute by combining 
these flags using the logical OR operator. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

A return value of 0 indicates that access is allowed. If access is denied or 
the file cannot be found, — 1 is returned. Additional error information 
can then be found in the external integers errno and _OSERR. 
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access Check file accessibility 
(continued) 


Example 


/* Check to see if the file s:myconfig */ 
/* exists and is writable. */ 


((include <stdio.h> 


void main(void) 


I 


if (access( "s:myconfig" ,F_0K I W_OK)==0) 

( 

printf ( "yes\n " ) ; 


else 

{ 

printf ( "no\n" ) ; 
exit ( EXIT-FAILURE ) ; 


) 


See Also chmod, errno, _OSERR 
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acos Arccosine function 
Synopsis # include <math.h> 


r = acos(x) ; 

double r; /* result */ 
double x; /* angle */ 


Description The acos routine computes the arccosine of x and returns the angular 
value expressed in radians. The result is constrained from 0 to 7 t. The 
argument x must be between —1.0 and 1.0, inclusive, or a DOMAIN 
error will be raised. 


Portability ANSI 

Returns This function returns the arccosine of the angle expressed in radians. 
See Also cos, matherr 
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argopt Get options from an argument list 
Synopsis i include <stdlib.h> 

optd = argopt(argc,argv,opts,argn,optc) ; 


char *optd; 

/* 

option data pointer 

*/ 

int argc; 

/* 

argument count 

*/ 

const char *argv[ ] ; 

/* 

argument vector 

*/ 

const char *opts; 

/* 

options expecting data 

*/ 

int *argn; 

/* 

next argument number (changed) 

*/ 

char *optc; 

/* 

option character (changed) 

*/ 


Description This function examines an argument list to find the next option argument, 
using the conventions similar to those of the UNIX shell command 
processor. These conventions follow: 

□ An option is an argument that begins with a slash (/) or a dash (a 
minus sign) and appears between the command verb (argv [ 0 ] ) and 
the first non-option argument. This function recognizes either a slash 
or a dash because these characters are used by other systems. 

□ The character immediately following the dash is called the option 
character, and it may be followed by a character string known as the 
option data. 

□ If the option character appears in the opts string, then the data can 
be separated from the character by white space. In effect, this means 
that the data might be in the next argv entry if it does not follow the 
option character in the current entry. 

□ A dash or slash followed by a blank or a dash indicates the end of the 
options. 

Each time argopt is called, it finds the next option in the argument 
array and updates the integer referenced by the argn parameter. On the 
first call, you should set this integer to 1, since argv [ 0 ] points to the 
command verb. The argc and argv items are normally the same as 
those passed to your main program, and they are not changed as a result 
of the argopt calls. The option character is returned in the byte 
referenced by the optc parameter, and the function returns a pointer to 
the option data string or to a NULL byte. If the next entry in the argv 
vector is not an option, then the function returns a NULL pointer. 

The opts item provides some flexibility in the way the option data are 
handled. If the opts parameter points to an empty string, then any 
option data must immediately follow the option character. However, if the 
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argopt Get options from an argument list 
( continued ) 


opts parameter is not empty, then it lists the option characters that 
always have data. For those characters, the data can be preceded by 
white space in the command line. What this actually means is that the 
argopt function will look at the next entry in the argv vector if the 
option character is not followed by a data string. If that next entry does 
not begin with a dash, then it is taken as the option data. See the 
examples below for clarification. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


Portability SAS/C 

Returns If the next argument is not an option, the function returns a NULL 

pointer. Otherwise, it returns a pointer to the option data, which will be 
an empty string if there were no data. Also, if an option was found, the 
character is placed into the byte referenced by the optc parameter, and 
the argn parameter is adjusted to index the next entry in the argv 
vector. 


Example /* 

* Assume that this program is invoked with the following 

* command lines 


* myprog -x -ypdq -z -g moo -g 

* 


The output 

will then be 

Option: 

x Data: 

Option: 

y Data: pdq 

Option: 

z Data: 

Option: 

m Data: oo 

Option: 

g Data: 

Arg[8|: 

blah 


*/ 

({include <stdio.h> 
{{include <stdlib.h> 


blah 


char opts[] = "gx"; 
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argopt Get options from an argument list 
(continued) 

void main(int argc, char *argv[]) 

{ 

char option, *odata; 
int next; 

next = 1 ; 

while((odata = argopt(argc,argv,opts,6next,6option) ) 
! = NULL) 

( 

printf ( "Option: Xc, Data: 5Ss\n" , option, odata) ; 

) 

for (; next < argc; next++) 

{ 

printf ( "Arg[ £d] : Xs\n" ,next,argv[next] ) ; 

} 


See Also 


main 
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asctime 

Synopsis 


Description 

Portability 

Returns 


Example 


Generate an ASCII time string 
Sinclude <time.h> 
s = asctime(t); 

char *s; /*points to time string */ 

const struct tm *t; /*points to time structure */ 

This function converts a time structure into an ASCII string. The time 
structure argument t is usually returned by the gmtime or local time 
function. 

ANSI 

This function returns an ASCII string of exactly 26 characters having the 
form: 

“DDD MMM dd hh:mm:ss YYYY\n\0” 

DDD is the day of the week, MMM is the month, dd is the day of the 
month, hh:mm:ss is the hour:minute:seconds, and YYYY is the year. An 
example is 

"Wed Sep 04 15:13:22 1985\n\0" 

The time pointer returned by the function refers to a static data area that 
is shared by both the ctime and asctime functions. 

finclude <stdio.h> 

((include <time.h> 

void main(void) 

( 

struct tm *tp ; 
long t; 

time ( St) ; 

tp = localtime(St) ; 

printf( "Current time is Ks\n" ,asctime(tp ) ) ; 

) 


See Also 


ctime, gmtime, localtime, strftime 
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asm 

Synopsis 


Description 

Portability 
Returns 
See Also 


Arcsine function 
({include <math.h> 
r = asin(x) ; 

double r; /* result*/ 

double x; /* angle */ 

The as in routine computes the arcsine and returns an angular value 
expressed in radians. The result is constrained as — n/2 to tc/2. The 
argument must be between —1.0 and 1.0, inclusive, or a DOMAIN error 
will be raised. 

ANSI 

This function returns the arcsine of the argument expressed in radians. 
matherr, sin 



142 Chapter 7 


assert Assert program validity 
Synopsis § include <assert.h> 
assert(x) ; 

— assert(x, file, line) ; 

int x; /* expression to check for nonzero value */ 

const char *file; /* source file name */ 
int *line; /* source line number */ 

Description The assert macro tests an expression x for validity (nonzero value). If 
a condition in your program is false (0), the assert macro is a quick 
way to abort the program and print an error message to stderr. If the 

expression is false, then the macro calls the assert function with the 

expression in text form plus the source filename (as defined in the 

FILE macro) and line number (as defined in the LINE 

macro), also as text strings. The default version of the assert 

function prints a message to stderr and aborts with an exit code of 1. 

Note: You cannot call assert or assert from a shared library. 

To define the macro, include the assert . h header file in your 
program. The assert . h file contains two versions of the macro, a null 
version and the normal code-generating version. Using the null version 
allows you to strip the assertion code from your program without 
removing the assert calls. To use the null version, define the symbol 
NDEBUG in one of your header files. If you define NDEBUG in one of your 
header files, the header file containing the NDEBUG definition must be 
included before the assert.h file. If the symbol NDEBUG is defined, the 
null version of the macro is used. If the symbol NDEBUG is not defined, 
the normal code-generating version applies. 


Portability ANSI 
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assert Assert program validity 
( continued ) 

Example ({include <stdio.h> 

{{include <assert.h> 

/* Make sure integer x is positive */ 

void postest(int x) 

( 

assert(x >= 0) ; 

) 

void main(void) 

( 

postest( 5) ; 

printf("5 is a positive integer\n"); 
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astcsma 

Synopsis 

Description 

Portability 

Returns 

Example 


AmigaDOS string pattern match (anchored) 

{(include <string.h> 
length = astcsma( s , p ) ; 

int length; /* length of matching string */ 

const char *s; /* string being scanned */ 

const char *p; /* pattern string */ 

The function astcsma performs a simple anchored AmigaDOS style 
pattern match. That is, you can specify the wildcards # ? in the pattern 
string. The pattern must match at the beginning of the specified string. 

This function is not available if the _STRICT_ansi flag has been 
defined. 

AmigaDOS 

This function returns the length of the matching string or 0 if there was 
no match. 

/* Show all files matching the pattern "|?.c" */ 

{(include <stdio.h> 

{(include <stdlib.h> 

{{include <string.h> 

{{include <sys/types .h> 

{{include <sys/dir.h> 

void main(void) 

{ 

DIR *dfd; 

struct direct *dptr; 


dfd=opendir ( ; /* opens the current directory */ 
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astcsma AmigaDOS string pattern match (anchored) 

( continued ) 

if (dfd ! = NULL) 

{ 

while ( (dptr=readdir (dfd) ) !=NULL) 

( 

if ( astcsma (dptr->d_name, "#?.c") !=0) 

I 

printf ( "Ks\n" ,dptr->d_name) ; 

) 

) 

closedir (dfd) ; 

) 

) 


See Also stcpm, stcpma, stcsma 
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atari 

Synopsis 

Description 

Portability 

Returns 

See Also 


Arctangent function 
flinclude <math.h> 
r = atan(x) ; 

double r; /* result */ 

double x; /* angle */ 

The a tan routine computes the arctangent of x and returns an angular 
value expressed in radians. The result is constrained as —n to n. 

Since the tangent becomes very large for angles close to k/2, the 
atan2 function is often used to avoid computations with large numbers 
that might easily overflow. With the atan2 function, you can express the 
large tangent value as a quotient of two more reasonable numbers. 

ANSI 

This function returns the arctangent of the argument expressed in 
radians. 

atan2, raatherr, tan 
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atan2 Arctangent of x/y 

Synopsis ((include <math.h> 

r = atan2(x,y) ; 

double r; /* result; */ 
double x,y; /* angle */ 

Description The a tan 2 routine computes the arctangent of x/y and returns an 

angular value expressed in radians. The result is constrained as — n to n. 
You can express the large tangent value as a quotient of two more 
reasonable numbers. 

Since the tangent becomes very large for angles close to n/2, the 
a tan 2 function is often used to avoid computations with large numbers 
that might easily overflow. 

Portability ANSI 

Returns This function returns the arctangent of the argument expressed in 
radians. 

See Also atan, matherr, tan 
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atexif Set an exit trap 
Synopsis ((include <stdlib.h> 


error = atexit(func) ; 

int error; /* zero for success */ 

void ( *f unc ) ( void) ; /* trap function pointer */ 

Description This function registers an exit trap, which will be called when the 

program exits. There is no limit to the number of exit functions you can 
have. Exit functions are called in last in, first out (LIFO) order. 

After you establish an exit routine, you cannot prevent it from being 
called. All functions will be called, in reverse order of their registration, 
when the program exits. 

At the time the exit traps are called, all files opened with the open or 
f open function are still open, unless specifically closed by your code. All 
memory allocated with the malloc function and other ANSI memory- 
allocation functions is still allocated unless specifically freed by your code. 
After the exit traps have been called, these resources are freed. 

Portability ANSI 


Returns A zero is returned for success and a nonzero value is returned if an 
error is encountered. 


See Also exit 
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atof 

Synopsis 

Description 

Portability 

Returns 

Example 


Convert an ASCII string to a floating-point number 
jfinclude <stdlib.h> 
d = atof (p) ; 

double d; /* floating point result */ 

const char *p; /* input string pointer */ 

This function converts an ASCII input string into a double-precision 
floating-point number. The string can contain leading white space and a 
plus or minus sign, followed by a valid floating-point number in normal 
or scientific notation. If scientific notation is used, there can be no white 
space between the number and the exponent. For example, the following 
is a valid number in scientific notation: 

123 . 456e-53 

ANSI 

This function returns the double-precision floating-point equivalent of the 
ASCII string. 

/* This program tests the atof function. */ 

^include <stdio.h> 
jjinclude <math.h> 

void main(void) 

( 

char buf f [ 80 ] ; 
double d; 

while( 1 ) 

( 

printf ( "\nEnter a number: "); 
if (fgets(buff ,sizeof (buff ) ,stdin) == NULL) 


1 


break; 
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atof Convert an ASCII string to a floating-point number 
(continued) 

if (buff [ 0 1 == • \0 ’ ) 

( 

break; 

} 

d = atof (buff ) ; 
printf ("5Se\n",d) ; 

} 

printf ( "\n" ) ; 


See Also atoi, atol, stcd_i, stccLJL, strtod 
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atoi 

Synopsis 


Description 


Portability 

Returns 


Convert an ASCII string to an integer 

{(include <stdlib.h> 
x = atoi(s) ; 
int x; 

const char *s; 

This function converts an ASCII string into a normal integer. The string 
must have the form: 

[whitespace][sign]digits 

Whitespace indicates optional leading white space, sign indicates an 
optional + or — sign character, and digits is a contiguous string of digit 
characters. Once the digit portion is reached, the conversion continues 
until a nondigit character is reached. No check is made for integer 
overflow. 

ANSI 

This function returns the integer equivalent of the ASCII string. 


See Also atof , atol, stcd_i, stcd_l, strtod, strtol 
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atol 

Synopsis 


Description 


Portability 

Returns 


Convert an ASCII string to a long integer 

jfinclude <stdlib.h> 

y = atol(s) ; 

long int y; 
const char *s; 

This function converts ASCII strings into long integers. The string must 
have the form: 

[whitespace][sign]digits 

Whitespace indicates optional leading white space, sign indicates an 
optional + or — sign character, and digits is a contiguous string of digit 
characters. Once the digit portion is reached, the conversion continues 
until a nondigit character is reached. No check is made for integer 
overflow. 

ANSI 

This function returns the long integer equivalent of the ASCII string. 


See Also atof , atoi, stcd_i, stcd_l, strtod, strtol 
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—autoopenfail Terminate program if OpenLibrary fails 
Synopsis void autoopenfail (char *lib); 

Description If you declare but do not define a system library base in your own code, 
the library base is automatically initialized. If the autoinitialized libraries 

cannot be opened, autoopenfail is called. By default, 

autoopenfail prints a message indicating which library could not 

be opened and then terminates your program. 

The source code for autoopenfail is in 

sc : sour ce/autoopenf ail . c. 

For complete information on initializing system library bases, refer to 
Chapter 10, “ Using Startup Modules, Autoinitialization, and 
Autotermination Functions,” in SAS/C Development System User’s Guide, 
Volume 1. 

Portability AmigaDOS 
See Also oslibversion 
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bldmem 

Synopsis 


Description 

Portability 
Returns 
See Also 


Build a memory pool of a specified size 
jfinclude <stdlib.h> 
i=bldmem(n) ; 

int n; /* number of IK-byte blocks in pool */ 

int i; /* -1 for failure */ 

The bldmem function uses the sbrk function to get up to n contiguous 1 
megabyte blocks of memory for the pool. If n is 0, the pool is initialized, 
but no memory is allocated. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

OLD 

This function returns a —1 if the sbrk function fails, 
getmem, getml, rlsmem, rlsml, sbrk, sizmem 
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bsearch 

Synopsis 


Description 


Portability 

Returns 


Perform a binary search 
({include <stdlib.h> 


void *bsearch(srch, array, n, size,cmp); 


const void *srch; 

/* 

object searched for 

*/ 

const void *array; 

/* 

pointer to array to search 

*/ 

size_t n; 

/* 

number of members of array 

*/ 

size_t size; 

/* 

size of each element 

*/ 

int (*cmp) (const void 

* i 

const void *) ; 



/* 

pointer to comparison function 

*/ 


The bsearch function scans a sorted array pointed to by the array 
pointer for a match with a search value addressed by the srch pointer, 
array is a pointer to the first element of the array to be scanned, n is 
the number of elements in the block, and size is the size of each 
element in bytes. 

The bsearch function calls a user-provided comparison function, cmp, 
passing it pointers to the two objects being compared. The first pointer 
points to the key. The second pointer points to an array element. 

The cmp function returns the following values: 

□ a negative integer if the first of the two objects is less than the second 

□ a positive integer if the first object is greater than the second 

□ 0 if the two objects are equal. 

The array to be searched should be sorted in ascending order. 

ANSI 

The bsearch function returns a pointer to the element that matches the 
search value. If no match can be found, the bsearch function returns a 
NULL pointer. 


See Also qsort 
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calloc Allocate and clear memory 

Synopsis ((include <stdlib.h> 

b = calloc(nelt,esize) ; 

void *b; /* block pointer */ 

size_t nelt; /* number of elements */ 
size_t esize; /* element size */ 

Description This function is called a level 3 memory allocation function because it 

calls upon level 2 functions. This level is fully compatible with UNIX and 
with the ANSI Standard. 

The calloc function uses the malloc function to get a level 3 
memory block whose size in bytes is given by 

n = nelts * esize; 


Then, the block is cleared to zeroes. The calloc function returns a 
NULL pointer if the block cannot be allocated. The calloc function can 
only allocate 64 kilobytes at a time if you are compiling with short 
integers. 

Note: The level 1 function rbrk frees all level 2 and level 3 blocks. 
You can free the block returned from the calloc function with the 
free function. 

Portability ANSI 

Returns A NULL pointer is returned if there is not enough space for the requested 
block. 

Example The following example allocates an array large enough for 100 long 
integers and initializes the block to zeroes. 


long *lary; 


lary=calloc( 1 00 , sizeof ( long) ) ; 
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callOC Allocate and clear memory 
(continued) 

The following example allocates an array of data structures. 

iinclude <stdio.h> 
iinclude <stdlib.h> 

jfdefine MAXENTRIES 50 

struct data 

I 

int age; 
char name[ 30 ] ; 
int height; 

); 

struct data *datap; 

void init(void) 

( 

if ( (datap=calloc(MAXENTRIES,sizeof (struct data) ) )==NULL) 

{ 

abort( ) ; 



void main(void) 

( 

init ( ) ; 

printf( "Memory allocated. \n" ) ; 
f ree(datap) ; 

} 


See Also free, getmem, malloc, rbrk, realloc, rlsmem, sbrk 
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ceil 

Synopsis 

Description 

Portability 

Returns 

Example 


Get floating-point limits 
((include <math.h> 
x = ceil(y ) ; 
double x,y; 

The ceil function returns the smallest whole number not less than the 
specified real number. 

ANSI 

The result is a real number. 

((include <stdio.h> 

((include <math.h> 

double r; 

void main(void) 

I 

r = ceil (523.96) ; /* r contains 524.0 */ 

printf ( "ceil(523.96) = JSlf\n", r); 

} 


See Also 


floor 
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chdir 

Synopsis 


Description 

Portability 

Returns 


Change the current directory 
({include <stdio.h> 
error = chdir(path) ; 

int error; /* 0 if successful */ 

const char *path; /* points to new directory path string */ 

This function changes the current directory to the specified path. For 
AmigaDOS, the path may begin with a drive or volume name and a 
colon. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

If the return value is nonzero, then the operation failed. An AmigaDOS 
error code will be in the external integer _OSERR, and a UNIX error 
code will be in the external integer err no. 


See Also errno, getcd, getcwd, mkdir, _OSERR, rmdir 
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Chgclk Change the system clock 
Synopsis § include <dos.h> 

error = chgclk(clock) ; 
int error; 

const unsigned char *clock; 

Description The chgclk function changes the setting of the system clock to the value 
specified in the array. The array’s contents are as follows: 


Byte 

Contents 

clock[0] 

day of the week (0 for Sunday) 

clock[l] 

years since 1980 

clock[2] 

month (1 to 12) 

clock[3] 

day (1 to 31) 

clock[4] 

hour (0 to 23) 

clock[5] 

minute (0 to 59) 

clock[6] 

second (0 to 59) 

clock[7] 

hundredths (0 to 99) 


This function changes only the system clock. To make the change 
permanent, you must use the AmigaDOS command 
setclock opt save. 

Portability AmigaDOS 

Returns If the array is invalid or the operation failed, the chgclk function 
returns a nonzero value. 

See Also errno, getclk, _OSERR 
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Chk_Abort, 

chkabort 

Synopsis 

Description 


Check for a break character 


((include <dos.h> 
void chkabort(void) ; 
void Chk-Abort(void) ; 

These functions force immediate checking for the Control-C and Control-D 
break characters. Normally, this check only occurs when level 1 I/O is 
performed. The chkabort function provides a mechanism for detecting 
the break characters at other times, an important function for programs 
that do little or no I/O processing. 

If the break key is detected, the break trap is executed. The break trap 
is simply a function that gets called whenever the user enters Control-C. 

If the break trap returns a zero value, control returns to the calling 
function; otherwise, the program terminates. If the program is invoked 
from the Workbench, the default handler displays a requester allowing 
the user to abort the program; otherwise, the default handler prints a 
message to the Command Line Interpreter (CLI) and aborts. 

The chkabort function ignores the break characters Control-E and 
Control-F. The chkabort function may be replaced with calls to the 
onbreak or signal functions. 

To turn off Control-C checking, you can compile with the nochk abort 
option, or you can include the following prototype and function definition 
in your code: 

void regargs — chkabort (void) ; 

void regargs — chkabort (void) 

{ 


This code replaces the function normally called for a Control-C with a 
function that does nothing. 
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Chk_Abort, Check for a break character 

chkabort 

( continued ) 

To retain checking for Control-C, but to change the action taken when 
Control-C is pressed, include the following: 

void — regargs _CXBRK( void) ; 

void — regargs _CXBRK(void) 

( 

/* your-code-here */ 

) 

Portability AmigaDOS 
See Also _CXBRK, onbreak, signal 
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chkml 

Synopsis 

Description 

Portability 
Returns 
See Also 


Check for the largest memory block 
({include <stdlib.h> 
size = chkml( void) ; 
long size; 

This function returns the size, in bytes, of the largest block that is 
currently available in the level 2 memory pool without calling the 
operating system to supply additional heap space. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The return value is the size of the largest level 2 block, 
getmem, getml, rlsraem, rlsml, sizmem 
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chkufb Check a level 1 file handle 
Synopsis # include <ios1.h> 
ufb = chkufb(fh); 

struct UFB *uf b; /* pointer to UNIX file block */ 
int fh; /* file handle */ 

Description This function checks if a file handle is currently associated with a level 1 
file. Normally, it is used internally by the open, close, read, write, 
1 seek, and tell functions. The UFB structure is defined in the header 
file ios 1 .h. For AmigaDOS, this structure has the following form: 

struct UFB 


struct UFB *ufbnxt; 

/* 

next UFB 

*/ 

int ufbflg; 

/* 

flags 

*/ 

long ufbfh; 

/* 

file handle 

*/ 

char *ufbfn; 

/* 

file name 

*/ 


The structure pointer uf bnxt points to the next entry in the linked list 
containing all currently open level 1 files. The integer ufbf lg contains 
the mode flags specified in the call to the open function. The long integer 
ufbfh contains the file handle, uf bf n is a pointer to the character 
string containing the filename. 

The external data name uf bs refers to a linked list of UFB 

structures, and the external integer nuf bs indicates how many 

structures are in the linked list. 

Portability SAS/C 

Returns If no UFB is currently attached to the file handle, a NULL pointer is 
returned. 


See Also nufbs, ufbs 
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chmod 

Synopsis 


Description 


Portability 

Returns 


Change a file’s protection mode 

((include <stdio.h> 

Sinclude <fcntl.h> 

error = chmod ( name ,mode ) ; 

int error; /* error code */ 

const char *name; /* file name */ 
int mode; /* protection mode */ 

This function changes a file’s protection mode. It is compatible with 
UNIX, although AmigaDOS also provides separate delete protection for 
each file. The mode argument should be formed combining any of the 
following symbols, which are defined in the file f cntl . h, using the 
logical OR operator: 


Value 

S—IWRITE 

S—IREAD 

S IEXECUTE 

S IDELETE 

S—IPURE 

S I ARCHIVE 

S ISCRIPT 


Meaning 
write permission 
read permission 
execute permission 
delete permission 
set the bit 

indicate the file has been backed up 
indicate the file is a system script 


This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

If the operation is successful, the function returns 0. Otherwise, it 
returns —1 and places error information in the external integers err no 
and OS ERR. 
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Chmod Change a file’s protection mode 
( continued ) 

Example /* This example changes file "xyz/pdq.x" */ 

/* so it can be read and written. */ 

((include <stdio.h> 

((include <stdlib.h> 

((include <fcntl.h> 

void main(void) 

{ 

if ( chmod ( "xyz/pdq.x" , S—IWRITE I S_IREAD ) ) 

( 

perror( "Change mode"); 
exit ( EXIT-FAILURE ) ; 

) 

} 

See Also access 
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clearerr 

Synopsis 


Description 


Clear a level 2 I/O error flag 
((include <stdio.h> 
void clearerr ( fp) ; 

FILE *fp; /* file pointer */ 

This macro clears the error flag and end-of-file flag of the file pointed to 
by the f p pointer. Once set, the error flag forces an end-of-file value to 
be returned any time the file is accessed until the flag is reset. 


Portability ANSI 
See Also clrerr, ferror 
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clock Measure program processor time 

Synopsis ((include <time.h> 
x = clock( void) ; 
clock_t x; 

Description The clock function returns an approximation of the amount of 

processor time used by the program, relative to the base point. The base 
point for the clock function is the time the program’s startup code was 
run. clock approximates the amount of processor time used by the 
program by calculating the elapsed time since the base point. 

You can use the clock function to determine the amount of processor 
time used by calling the clock function twice in the same program and 
calculating the difference between the values returned. 

The value returned is of type clock_t. The value returned is in 
fractions of a second, where a value of CLOCKS_PER_SEC represents 
one second of processor time. (clock_t and CLOCKS_PER_SEC are 
defined in the file time . h.) In this implementation, clock_t is defined 
as an unsigned long integer and CLOCKS_PER_SEC is 1,000. 

The value returned by the clock function is of relatively low accuracy 
and depends on the extent of other system activity. Values returned by 
the clock function are likely to be inconsistent from one execution of a 
program to another. To get more accurate values, make sure your 
program is the only one running in the system. 

Portability ANSI 

Returns The clock function returns the number of seconds since the base time. 
If an accurate value cannot be returned, ( clock_t ) - 1 is returned. 

Example /* This example determines the processor time */ 

/* required to compute 1000 logarithms. */ 

((include <time.h> 

((include <math.h> 

((include <stdio.h> 

void main(void) 

1 

clock_t start, end; 
double index; 
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clock Measure program processor time 
(continued) 


/* Time used before start of computation */ 
start = clock{ ) ; 

for (index = 1.0; index <= 1000.0; ++index ) 
(void)log (index); 

end = clock( ) ; 

/* Calculate the difference in time and print */ 
printf ( "Processor time used = JSd\n", 

(end - start) / CLOCKS_PER_SEC) ; 

} 


See Also system, time 
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close 

Synopsis 


Description 


Portability 

Returns 

Example 
See Also 


Close a level 1 file 

((include <fcntl.h> 

error = close(fh); 

int error; /* non-zero if error */ 
int fh; /* file handle */ 

This function closes a level 1 file that was previously opened with the 
open function. Any pending output is completed and the file directory is 
updated. 

All level 1 files are automatically closed when your program 
terminates, but it is good programming practice to close a file when you 
are finished with it. One reason for doing this is to free up the operating 
system resources (for example, control blocks and buffers) that are 
allocated for the file while it remains open. 

UNIX 

The function returns 0 if it is successful. Otherwise, it returns — 1 and 
places additional error information into the external integers err no and 
-OSERR. 

See the open function. 

—dolose, fclose, open 
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closedir 

Synopsis 

Description 

Portability 
See Also 


Terminate the directory operation 
((include <sys/dir.h> 
void closedir(dfd) 

DIR *dfd; /* directory file descriptor */ 

This function closes a directory previously opened with the opendir 
function. All memory and systems locks associated with the directory file 
descriptor are freed. You must call the closedir function for each 
descriptor opened with the opendir function to reclaim the memory and 
the lock associated with the descriptor. 

UNIX 

opendir, readdir, seekdir, telldir 
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clrerr 

Synopsis 

Description 

Portability 
See Also 


Clear a level 2 I/O error flag 
^include <stdio.h> 
void clrerr ( fp) ; 

FILE *f p ; /* file pointer */ 

This macro clears the error flag associated with the specified level 2 file. 
Once set, the error flag forces an end-of-file value to be returned any time 
the file is accessed until the flag is reset. This function duplicates the 
ANSI clearerr macro and is provided for compatibility. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

clearerr, ferror, fopen 
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COS 

Synopsis 


Description 

Portability 

Returns 


Cosine function 
finclude <math.h> 
r = cos(x) ; 

double r; /* result */ 
double x; /* angle */ 

The cos function computes the cosine of angles expressed in radians. 
ANSI 

This function returns the cosine of the argument. 


See Also 


raatherr 
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cosh 

Synopsis 


Description 

Portability 

Returns 


Hyperbolic cosine function 
({include <math.h> 
r = cosh(x) ; 

double r; /* result */ 

double x; /* angle */ 

The cosh function computes the hyperbolic cosine of an angle. A range 
error occurs if the hyperbolic cosine is too large to be represented by a 
double. 

ANSI 

This function returns the hyperbolic cosine of the argument expressed in 
radians. 


See Also exp, matherr 
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cot 

Synopsis 


Description 

Portability 

Returns 


Cotangent function 
((include <math.h> 
r = cot(x); 

double r; /* result */ 

double x; /* angle */ 

The cot function computes the cotangent of an angle measured in 
radians. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

This function returns the cotangent of the argument expressed in radians. 


See Also matherr 
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creat 

Synopsis 


Description 


Portability 

Returns 

See Also 


Create a level 1 file 

ifinclude <fcntl.h> 

fh = creat ( name, prot) ; 

int fh; /* file handle */ 

const char *name; /* file name */ 
int prot; /* protection mode */ 

This function is exactly the same as calling the open function in the 
following way: 

open ( name, 0_WR0NLY I 0_TRUNC I 0_CREAT , prot) 

The file is created if it does not exist and truncated if it does exist. 
Then, it is opened for writing. The protection mode can be any of the 
following: 


Value 

S — IWRITE 

S—IREAD 

S — IWRITE | S—IREAD 
0 


Meaning 

write permission 

read permission 

write and read permission 

write and read permission 


In the current AmigaDOS implementation, the protection mode is 
ignored. 

UNIX 

If the operation is successful, the function returns a file handle, which is 
an integer equal to or greater than 0. Otherwise, it returns — 1 and 
places error information in the external integers err no and _ OS err. 

chmod, close, errno, open, _ OSERR 
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ctime 

Synopsis 


Description 

Portability 

Returns 


Convert a time value to a string 
# include <time.h> 
s = ctime(t) ; 

char *s; /* points to time string */ 

const time_t *t; /* points to time value */ 

This function converts a time_t time value to a local time in the form of 
an ASCII string. 

The ctime function is equivalent to the following: 
asctime( local time(t) ) ; 

ANSI 

This function returns an ASCII string of exactly 26 characters having the 
form: 

“DDD MMM dd hh:mm:ss YYYY\n\0” 

DDD is the day of the week, MMM is the month, dd is the day of the 
month, hh:mm:ss is the hour: minute: seconds and YYYY is the year. An 
example is 

"Wed Sep 04 15:13:22 1985\n\0" 


The time pointer returned by the function refers to a static data area that 
is shared by both the ctime and as ctime functions. 
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ctime 

(continued) 

Convert a time value to a string 

Example 

# include <time.h> 
iinclude <stdio.h> 


void main(void) 


( 

time_t t; 


time( 6t) ; 

printf( "Current time is %•. 


",ctime(5t) ) ; 


See Also 


asctime, gmtime, localtime, strftime, time 
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—CXBRK 

Synopsis 

Description 


Portability 
See Also 


Print message and exit for Control-C processing 
jfinclude <dos.h> 
void -CXBRK(void) ; 

This function is called by chkabort when chkabort detects a 

Control-C signal. By default, _CXBRK prints **Break and exits. 

To turn off Control-C checking, you can compile with the nochk abort 
option, or you can include the following prototype and function definition 
in your code: 

void regargs chkabort( void) ; 

void regargs chkabort( void) 

{ 

) 


To retain checking for Control-C, but to change the action taken when 
Control-C is pressed, include the following: 

void regargs _CXBRK( void) ; 

void regargs _CXBRK(void) 

I 

/* your-code-here */ 

) 

This code replaces the functions normally called for a Control-C with 
functions that do nothing. 

AmigaDOS 

chkabort, chkabort 
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—CXFERR 

Synopsis 

Description 


Portability 
See Also 


Low-level floating-point error 

# include <math.h> 

void -CXFERR ( code ) ; 
int code; 

This function is called when an error is detected by one of the low-level 
floating-point routines, such as the arithmetic operations. Higher-level 

routines, such as the trigonometric functions, use the matherr 

function. 

You cannot call this function. However, you can replace this error trap 
with an application-dependent routine, as long as it stores the error code 
in the global integer _ FPERR. Some of the math functions check the 
—FPERR integer to see if low-level errors occurred. To replace this 
function, include a prototype as well as the error trap function in your 
source code. The function and prototype should be named —CXFERR. 

The error code passed to the —CXFERR function indicates the type of 
floating-point anomaly that occurred, as follows: 


Symbol 

Value 

Meaning 

_ FPEUND 

1 

underflow 

_ FPEOVF 

2 

overflow 

FPEZDV 

3 

divide by zero 

_ FPENAN 

4 

not a number 

_ FPECOM 

5 

not comparable 


If the _ STRICT—ANSI flag has not been defined, equivalent names 
without the leading underscore are also defined for compatibility with 
previous releases of the compiler. 

These codes are defined in the file math . h. 

This routine was named CXFERR in Version 5 and previous versions. 
SAS/C 

matherr 
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_CXOVF 

Synopsis 

Description 


Portability 

Example 


Default stack-overflow handler 
_CX0VF( void) ; 

This function is the default stack-overflow handler. When called, it puts 
up a requester indicating the stack-overflow state for the current 
program. After the user clicks on the requester, this routine terminates 
the program. 

This function is automatically invoked by the stack-overflow detection 
code. You cannot call this function. However, you can replace this 
function with your own replacement function. To replace the _CXOVF 
function, include a prototype as well as the function in your source code. 
The function and prototype should be named _CXOVF. 

Sample source code is provided in the source directory. 

This routine was named cxovf in Version 5 and previous versions. 

SAS/C 

/* This is a replacement overflow handler that simply */ 

/* restarts the program at a safe known spot. */ 

({include <setjmp.h> 

extern jmp_buf safe_spot; 

void stdargs _CX0VF(void) 

{ 


longjmp(safe_spot, 1); 
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datecmp Compare two AmigaDOS dates 
Synopsis # include <dos.h> 

status = datecmp(d1, d2); 


int status; 

/* result of comparison: 

*/ 


/* 0 if equal 

*/ 


/* -1 if dl > d2 

*/ 


/* 1 if dl < d2 

*/ 


const struct DateStamp *d1; /* first date to compare */ 

const struct DateStamp *d2; /* second string to compare */ 

Description The datecmp function compares two date vectors (three long words) to 
see if they are equal. To be equal, all of the days, minutes, and ticks must 
match. If they are unequal, the datecmp function returns an appropriate 
value. 

Portability AmigaDOS 

Returns If the dates match as described above, then 0 is returned. If the first date 
is greater than the second date, then — 1 is returned. Otherwise, 1 is 
returned. 

See Also DateStamp ( The AmigaDOS Manual, 3rd Edition ) 
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_dclose 

Synopsis 


Description 


Portability 

Returns 

See Also 


Close an AmigaDOS file 
((include <dos.h> 
error = _dclose(fh); 

int error; /* 0 for success, -1 for error */ 

long fh; /* file handle */ 

This function closes an AmigaDOS file that was opened with the 
_ dcreat, _dcreatx, or _dopen function. AmigaDOS will not 
automatically close these files for you. One reason for closing files is to 
free up the operating system resources (control blocks and buffers) which 
are allocated for the file while it remains open. 

This function is obsolete and provided for compatibility only. Use the 
AmigaDOS Close function instead. 

OLD 

If the operation is successful, the function returns 0. Otherwise, it 
returns —1 and places error information in the external integers err no 
and —OSERR. 

Close ( The AmigaDOS Manual, 3rd Edition), —dcreat, —dcreatx, 
—dread, _ dseek, _ dwrite, errno, —OSERR 
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—defeat Create an AmigaDOS file 
Synopsis # include <dos.h> 


fh = _dcreat(name, fatt) ; 


long fh; 

const char *name; 
int fatt; 


/* 

file 

handle (-' 

1 for error) */ 

/* 

file 

name */ 


/* 

file 

attribute 

*/ 


Description This function creates and opens an AmigaDOS file, returning the file 

handle. The —dcreat operation truncates the file if it already exists or 
creates the file if it does not exist. 

The file attribute argument is accepted to provide source-level 
compatibility with other systems, but is ignored under AmigaDOS. 

This function is obsolete and provided for compatibility only. Use the 
AmigaDOS Open function instead. 

Portability OLD 


Returns If the operation is successful, the function returns a file handle. 

Otherwise, it returns — 1 and places error information in the external 
integers errno and _ OSERR. 

See Also _dclose, —dcreatx, —dread, _ dseek, —dwrite, errno, Open 
(The AmigaDOS Manual, 3rd Edition), _OSERR 
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_dcreatx 

Synopsis 


Description 


Portability 

Returns 

See Also 


Create a new AmigaDOS file 

({include <dos.h> 

fh = _dcreatx(name,fatt) ; 

long fh; /*file handle (-1 for error) */ 

const char *name; /*file name */ 

int fatt; /*file attribute */ 

This function creates and opens an AmigaDOS file, returning the file 
handle. The _dcreatx operation fails if the file already exists, or creates 
the file if it does not exist. 

The file attribute argument is accepted to provide source-level 
compatibility with other systems, but is ignored under AmigaDOS. 

This function is obsolete and provided for compatibility only. Use the 
AmigaDOS Open function instead. 

OLD 

If the operation is successful, the function returns a file handle. 
Otherwise, it returns — 1 and places error information in the external 
integers err no and _OSERR. 

—dolose, —dcreat, —dread, _ dseek, _ dwrite, errno, Open 
(The AmigaDOS Manual, 3rd Edition), _ OS ERR 
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dfind Find a directory entry 
Synopsis ((include <dos.h> 


error = df ind( info, name, attr ) ; 


int error; 

struct FilelnfoBlock *info; 
const char *name; 
int attr; 


/* 0 if successful */ 

/* file information area */ 
/* file name or pattern */ 
/* file attribute bits */ 


Description The dfind function searches a directory for the first entry that matches 
the specified filename or filename pattern. 

The name argument must be a null-terminated string specifying the 
drive, path, and name of the desired file. The drive and path can be 
omitted, in which case, the current directory will be searched. You can 
use the AmigaDOS wildcard characters as defined in the AmigaDOS Users 
Manual for pattern matching in the name portion. For example, xy#? .b 
locates files in the current directory that begin with xy and have b as 

their extension. Setting the external integer location ms flag to a 

nonzero value causes all subsequent calls to the dfind function to use 
the MS-DOS * and ? characters for pattern matching in the name portion 
instead of the AmigaDOS characters # and ?. 

The attr argument specifies which file types are to be included in the 
search. If attr is 0, the search will include only normal files. Otherwise, 
the search will also include directories. 

The info argument points to a file information structure as defined in 
the dos . h header file. For AmigaDOS, this is the same as the AmigaDOS 
FilelnfoBlock structure. 


struct FilelnfoBlock { 


long 

f ib_DiskKey; 

long 

f ib_DirEntryType; 

char 

f ib_FileNarae[ 108 ] ; 

long 

f ib_Protection; 

long 

f ib_EntryType; 

long 

f ib_Size; 

long 

f ib_NumBlocks ; 

struct 

DateStamp fib_Date; 

char 

f ib_Comment[ 116]; 


info is a pointer to a file information block that must be allocated on 
a 4-byte (long word) boundary by the calling program. A common error 
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dfind 

( continued ) 


Portability 

Returns 

See Also 


Find a directory entry 


is failing to allocate the structure before calling the function. You can 
make sure the structure is long-word aligned by either declaring it with 

the aligned keyword or by allocating it dynamically with any SAS/C 

or system allocation function (such as the malloc orAllocMem 
function). 

AmigaDOS 

If the operation is successful, a value of 0 is returned. Otherwise, the 
return value is —1, and you can find additional error information in the 
external integers errno and _OSERR. 

dnext, errno, _OSERR 
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difftime 

Synopsis 

Description 

Portability 

Returns 

Example 


Compute the difference between two time_t values 
Sinclude <time.h> 
x = difftime(time2,time1 ) ; 
double x; 

time_t timel, time2; 

The difftime function computes the difference time 2 — timel in 
seconds, where time 2 and timel are values of type time_t (such as 
those returned by the time function). 

ANSI 

The difftime function returns the difference between two times in 
seconds. 

/* This example demonstrates a method of detecting */ 

/* when time-dependent data needs to be written */ 

Sinclude <time.h> 

Sinclude <stdio.h> 

void main(void) 

{ 

time_t last-written; /* Time data was last written */ 

FILE *f p ; 
int length; 

/* Open and write to a data file. Record */ 

/* when the file is written to. */ 


fp = fopen( "datafile" , "w" ) ; 

if (fp == NULL) printf ( "File wouldn't open\n"); 

length = fprintf ( fp, "Ss\n" , "Data is written to a file."); 

last-written = time(NULL); 


/* Additional code .... */ 
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difftime Compute the difference between two time_t values 
( continued ) 

/* Write additional data to file if the time since */ 
/* it was last written to is greater than 1 hour. */ 

if (difftime ( time(NULL), last-written) > 3600) 

length = fprintf ( fp, "Ss\n" , "More data is written."); 

f close( fp ) ; 

} 

See Also time 
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div 

Synopsis 

Description 

Portability 

Returns 


Example 


Compute the quotient and the remainder 
jjinclude <stdlib.h> 
x = div(y, z) ; 

div_t x; /* quotient and remainder */ 

int y; /* numerator */ 

int z; /* denominator */ 

The div function computes the quotient and remainder of the first 
argument, y, divided by the second argument, z. 

ANSI 

The div function returns a structure of type div_t, which contains both 
the quotient and remainder. The definition of the div_t type is 

typedef struct { 
int rem; 
int quot; 

) div_t; 

The return value is such that 
numer = quot * denom + rem 

The sign of the rem value is the same as the sign of the numer value. 

/* This example converts an angle in radians */ 

/* to degrees, minutes, and seconds */ 

Sinclude <stdio.h> 

Kinclude <stdlib.h> 
jfinclude <math.h> 

void main(void) 

{ 

double rad, angle; 
int deg, min, sec; 
div_t d; 


rad = 2.414; 
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div Compute the quotient and the remainder 
( continued ) 


/* Convert angle to seconds and discard fraction */ 
angle = rad * (180 * 60 * 60)/PI; 

sec = angle; 
d = div(sec, 60) ; 
sec = d.rem; 


d = div(d.quot, 60); 
rain = d.rem; 
deg = d.quot; 


printf("Xf radians = ftd degrees, Xd minutes, 
rad, deg, min, sec) ; 


%d seconds\n", 


See Also 


ldiv 



192 Chapter 7 


dnext Find the next directory entry 
Synopsis ((include <dos.h> 

error = dnext(info); 

int error; /* o if successful */ 

struct FilelnfoBlock *info; /* file information area */ 

Description The dnext function searches a directory for entries that match the 

specified filename or filename pattern. You must use the df ind function 
to locate the first matching file. Then, successive calls to the dnext 
function locate additional matching files. Each dnext call must be given 
the file information that was returned on the preceding call to the df ind 
or dnext function. 

The info argument points to a file information structure as defined in 
the dos . h header file. For AmigaDOS, this is the same as the AmigaDOS 
FilelnfoBlock structure. 

struct FilelnfoBlock ( 


long 

f ib_DiskKey; 

long 

f ib_DirEntryType; 

char 

fib_FileName[ 108 ] ; 

long 

f ib_Protection; 

long 

f ib_EntryType; 

long 

fib_Size; 

long 

f ib_NumBlocks ; 

struct 

DateStamp fib_Date; 

char 

fib_Comment[ 116); 


); 

info is a pointer to a file information block that must be allocated on 
a 4-byte (long word) boundary by the calling program. A common error 
is failing to allocate the structure before calling the function. You can 
make sure the structure is long-word aligned by either declaring it with 

the aligned keyword or by allocating it dynamically with any SAS/C 

or system allocation function (such as the malloc or AllocMem 
function). 

Portability AmigaDOS 

Returns If the operation is successful, a value of 0 is returned. Otherwise, the 

return value is —1, and you can find additional error information in the 
external integers err no and _OSERR. 
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dnext Find the next directory entry 
(continued) 


See Also df ind, errno, _OSERR 
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_d©pera 

Synopsis 


Description 


Portability 

Returns 

See Also 


Open an AmigaDOS file 

jf include <dos.h> 

fh = _dopen (name, mode ) ; 

long fh; /* file handle (-1 for error) */ 

const char *name; /* file name */ 
int mode; /* access mode */ 

This function opens an AmigaDOS file and returns the file handle. The 
mode argument must be a mode supported directly by AmigaDOS and 
defined in the Amiga header file dos/dos.h. 

Valid modes are as follows: 

MODE—OLDFILE 

opens an existing file with read and write access and positions the file 
pointer at the beginning of the file. 

MODE-NEWFILE 

opens a new file with read and write access and an exclusive lock. 
Deletes the old file. 

MODE—READWRITE 

opens an old file with a shared lock. Creates a new file if it doesn’t 
exist. 

This function is obsolete and provided for compatibility only. Use the 
AmigaDOS Open function instead. 

OLD 

If the operation is successful, the function returns a file handle. 
Otherwise, it returns — 1 and places error information in the external 
integers err no and_OSERR. 

—dolose, _ dcreat, —dcreatx, —dread, _ dseek, _ dwrite, errno, 
open, Open ( The AmigaDOS Manual, 3rd Edition), _ OSERR 
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dOS_packet Sends AmigaDOS output packet 


Synopsis # include <f unctions .h> 


retval = dos_packet( struct MsgPort *port, long type, long argl, 
long arg2, long arg3, long arg4, long arg5, 
long arg6, long arg7); 


long retval; 
struct MsgPort *port; 
long type; 
long argn; 


/* specific to packet type */ 

/* MsgPort to receive the packet */ 
/* type of message to send */ 

/* arguments for packet */ 


Description This function sends an AmigaDOS packet to a message port in the Amiga 
system. The type parameter is the specific packet type you want to send, 

such as CMD READ, and so on. The argl through arg7 parameters are 

argument values specific to the type of packet that you are sending. 

Portability OLD 

Returns The return value is specific to the packet type. 

See Also The AmigaDOS Manual, 3rd Edition (AmigaDOS Packets), DoPkt in 
AmigaDOS V2.0 and higher 
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dqsort Sort an array of double-precision floating-point numbers 
Synopsis ((include <stdlib.h> 
void dqsort(da,n) ; 

double *da; /* pointer to beginning of an array of doubles */ 
size_t n; /* number of elements in array */ 

Description The dqsort function sorts the specified array of double-precision 

floating-point numbers using the ACM 271 algorithm, more popularly 
known as Quicksort. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability SAS/C 


See Also fqsort, lqsort, qsort, sqsort, tqsort 
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drand48 

Synopsis 

Description 

Returns 

Portability 


Generate a random double-precision floating-point number (internal seed) 
{(include <math.h> 
x = drand48 ( ) ; 

double x; /* random double */ 

This function generates random numbers using the linear congruential 
algorithm and 48-bit arithmetic. The dr and 4 8 function uses an internal 
48-bit storage area for the seed value. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

The dr and 4 8 function returns double-precision floating-point values 
distributed uniformly over the interval from 0.0 up to but not including 
1 . 0 . 


UNIX 


See Also erand, jrand48, lcong48, rand, srand, srand48 
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—dread Read an AmigaDOS file 
Synopsis # include <dos.h> 

count = _dread( fh, buffer , length) ; 


unsigned int count; 
long fh; 
char ^buffer; 
unsigned int length; 


/* actual number of bytes read */ 
/* file handle */ 

/* data buffer */ 

/* number of bytes to read */ 


Description This function reads an AmigaDOS file whose handle was returned by the 
—dcreat, —dcreatx, or _dopen function. Under normal 
circumstances, the value returned should match the buffer length. If this 
value is — 1 or greater than the requested length, then some type of error 
occurred, and you should consult the external integers err no and 
—OSERR. If the actual length is less than the requested length when 
reading, then usually the file is exhausted. Similarly, if the actual length 
is less than the requested length for a write operation, then usually the 
device has no more space available. In both of these cases, it is still a 
good idea to check the external integers errno and _OSERR in case 
some malfunction caused the short count. 

This function is obsolete and provided for compatibility only. Use the 
AmigaDOS Read function instead. 

Portability OLD 


Returns If the operation is successful, the function returns the actual number of 
bytes transferred. Otherwise, it returns — 1 and places error information 
in the external integers errno and _OSERR. 

See Also —dolose, —dcreat, —dcreatx, _ dseek, _ dwrite, errno, —OSERR, 
Read (The AmigaDOS Manual, 3rd Edition) 
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— dseek Reposition an AmigaDOS file 
Synopsis ((include <dos.h> 


apos = _dseek( fh, rpos , mode) ; 


long apos; 
long fh; 
long rpos; 
int mode; 


/* actual file position */ 

/* file handle */ 

/* relative file position */ 
/* seek mode */ 


Description This function repositions an AmigaDOS file whose handle was returned 
by the dcreat, dcreatx, or dopen function. The seek mode is the 
same as for the lseek function, as follows: 

Mode Position 

0 relative to the beginning of the file 

1 relative to the current file location 

2 relative to the end of the file 


For modes 1 and 2, the rpos argument can be positive or negative, but 
the apos argument is always the actual (positive) position relative to the 
beginning of the file. 

This function is obsolete and provided for compatibility only. Use the 
AmigaDOS Seek function instead. 

Portability OLD 

Returns If the operation is successful, the function returns the actual file position, 
which is a long integer. Otherwise, it returns — 1L and places error 
information in the external integers err no and _ OSERR. 

See Also —dolose, —dcreat, —dcreatx, dopen, —dread, _ dwrite, errno, 
_ OSERR, Seek ( The AmigaDOS Manual, 3rd Edition) 
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_dwrite 

Synopsis 


Description 


Portability 

Returns 


Write to an AmigaDOS file 
{(include <dos.h> 


count = _dwrite( fh, buffer, length) ; 


unsigned int count; 
long fh; 
char *buffer; 
unsigned int length; 


/* actual bytes read or written */ 

/* file handle */ 

/* data buffer*/ 

/* number of bytes to read or write */ 


This function writes an AmigaDOS file whose handle was returned by the 
_ dcreat, —dcreatx or _dopen function. Under normal 
circumstances, the value returned should match the buffer length. If this 
value is —1 or greater than the requested length, then some type of error 
occurred, and you should consult the external integers err no and 
—OSERR. If the actual length is less than the requested length when 
reading, then usually the file is exhausted. Similarly, if the actual length 
is less than the requested length for a write operation, then usually the 
device has no more space available. In both of these cases, it is still a 
good idea to check the external integers errno and _OSERR just in case 
some malfunction caused the short count. 

This function is obsolete and provided for compatibility only. Use the 
AmigaDOS Write function instead. 

OLD 

If the operation is successful, the function returns the actual number of 
bytes transferred. Otherwise, it returns — 1 and places error information 
in the external integers errno and _OSERR. 

—dolose, —dcreat, —dcreatx, —dread, _ dseek, errno, —OSERR, 
Write ( The AmigaDOS Manual, 3rd Edition) 


See Also 
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ecvt 

Synopsis 


Description 


Portability 

Returns 


Convert a double-precision floating-point number to a string 
((include <math.h> 


s = ecvt(v, dig, decx, sign) ; 


char *s; 
double v; 
int dig; 
int *decx; 
int *sign; 


/* string pointer */ 

/* floating point value */ 

/* number of digits */ 

/* pointer to decimal index (returned) */ 
/* pointer to sign indicator */ 


This function converts a floating-point number into an ASCII character 
string consisting of digits only and terminated by a null character. 

The second argument, dig, indicates the total number of digits that 
should be generated. If the floating-point value contains fewer significant 
digits, zeroes are appended. If there are too many significant digits, the 
low-order (right-most) digit is rounded. 

The decx argument points to an integer that receives a value 
indicating where the decimal point should be placed in the string. For 
example, an index value of 3 indicates that the decimal point should be 
placed just after the third character in the string. A value of 0 means that 
the decimal point is just before the first character. If the index is 
negative, it indicates the number of zeroes that are between the decimal 
point and the first character. For example, —3 means that there are 
three zeroes between the decimal point and the beginning of the string. 

The sign argument points to an integer that is nonzero if the value v 
is negative. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

This function returns a pointer to a character string containing the ASCII 
equivalent of the float argument. 
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ecvt Convert a double-precision floating-point number to a string 
( continued ) 

Example # include <stdio.h> 

Uinclude <math.h> 

void main(void) 

{ 

int decx, sign; 
char *string; 

string = ecvt(3. 1415926535, 10, 6decx,Ssign) ; 

/* string => "3141592654" */ 

/* decx => 1 */ 

/* sign => 0 */ 

printf( "string = 55s, decx = 55d, sign = Xd\n", 
string, decx, sign); 

} 


See Also 


f cvt 
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emit 

Synopsis 

Description 

► Caution 

Portability 
Example 
See Also 


Emit 680x0 instruction word 
((include <dos.h> 

void emit( inst) ; 

int inst; 

The built-in function emit takes a constant 16-bit integer value 
corresponding to a 68000 assembly language instruction and inserts it 
inline with the code. However, it does not check whether the 16-bit value 

is a valid 68000 instruction. The emit function requires an integer 

parameter even though the assembly language instruction is only 16 bits 
long. 

Use this function carefully. Using this function incorrectly can create 
serious problems. ▲ 

SAS/C 

emit (0x4180) /* Assembler instruction for chk dO,dO */ 

getreg, putreg 
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_EPILOG Profiler —EPILOG hook 
Synopsis ff include <sprof.h> 

void asm _PR0L0G( register aO const char *where); 

void asm _EPILOG(register aO const char *where); 

Description If you compile a function with the profile option, —PROLOG and 

—EPILOG are automatically called when the function is entered or exited, 
respectively. —PROLOG and —EPILOG were designed for use by the 
sprof utility, but you can replace them with your own code and use 
them for any purpose. The SAS/C versions of —PROLOG and —EPILOG 
note the time the function was entered and exited and pass this 
information to the sprof utility, which produces a report telling you 
how much time was spent in each function. 

If you declare —PROLOG and —EPILOG in your code, make sure you 

declare them with the asm and register aO keywords as 

shown. If you declare either —PROLOG or —EPILOG, you must declare 
both, even if one of them simply returns immediately, 
sc : source/profile . c contains the source code for the SAS/C 
versions of —PROLOG and —EPILOG and the autoinitialization and 
autotermination functions associated with them. 

The parameter where is passed on the stack. It points to a character 
string of the following form: 

"\module\function\line" 

where 

module is the name of the file containing the function 
function is the name of the function 

line is the line number on which the function begins. 

For example, if you have a function f oo beginning on line 17 of the file 
f oo . c, the where parameter would be 

"\foo.c\foo\17" 

A null where parameter indicates that the PROFILER— ON or 
PROFILER— OFF macro has been called. PROFILE— OFF turns off 
profiling for the code that follows it. PROFILE— ON reinstates profiling. 
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—EPILOG Profiler _EPIL0G hook 
(continued) 


For more information about profiling, —PROLOG, —EPILOG, 

PROFILE— ON, and PROFILE— OFF, refer to the description of the sprof 
utility in SAS/C Development System User’s Guide , Volume 2. 


Portability SAS/C 
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erand48 Generate a random double-precision floating-point number (external seed) 
Synopsis # include <math.h> 
x = erand48 ( seed) ; 

double x; /* random double */ 

unsigned short seed [ 3 ] ; /* seed value (high bits in seed [ 0 ] ) */ 

Description This function generates random numbers using the linear congruential 
algorithm and 48-bit arithmetic. The erand48 function is provided for 
cases where several seeds are in use at the same time, so you can specify 
the seed on each function call. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability UNIX 

Returns The erand48 function returns double-precision floating-point values 

distributed uniformly over the interval from 0.0 up to but not including 

1 . 0 . 

See Also drand48, jrand48, lcong48, rand, srand, srand48 
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except Call the math error handler function 
Synopsis § include <math.h> 

r = except (type, name, argl , arg2 , retval ) ; 


double r; 

/* 

int type; 

/* 

const char *name; 

/* 

double argl ; 

/* 

double arg2; 

/* 

double retval; 

/* 


actual return value */ 
error type */ 
math function name */ 
first argument */ 
second argument */ 
proposed return value */ 


Description The except function is a SAS/C extension to UNIX that simplifies the 

interface to the matherr function by setting up the exception vector 

and processing the action code and return value. It is intended to ease the 
error-handling chore in user-written math functions. 

When your math function encounters an error, it should call the 
except function specifying one of the following error types, which are 
defined in the math . h header file: 


Symbol Code 

-DOMAIN 1 

-SING 2 

—OVERFLOW 3 

-UNDERFLOW 4 

TLOSS 5 

-PLOSS 6 


Meaning 
domain error 
singularity 

overflow (number too large) 
underflow (number too small) 
total loss of significance 
partial loss of significance 


If the —STRICT— ANSI flag has been defined, you must use the alternate 

entry point except. If the —STRICT— ANSI flag has not been 

defined, equivalent names without the leading underscore are also defined 
for compatibility with previous releases of the compiler. 


Portability SAS/C 
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except Call the math error handler function 
( continued ) 

Returns The actual return value (a double-precision floating-point value) is passed 
back. 

See Also fperr, matherr 
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exit 

Synopsis 

Description 


Portability 

Example 


Terminate program execution 
({include <stdlib.h> 
void exit(code) ; 
int code; 

This function terminates the current program and returns to the 
operating system. Before exiting, any functions specified in a call to the 
at exit function are called. Next, any open level 1 or level 2 files 
(opened with the open or fopen function) are closed. Finally, all level 1 
and level 2 memory is released back to the system. 

Your program must free any memory allocated with AmigaDOS 
functions and close any file opened with the AmigaDOS functions. 

From within a shared library, you must not call any library functions 
that terminate your program. For example, you cannot call exit, 

exit, or abort from a shared library. You also cannot use set jmp 

and long jmp to jump across a call from the program into the library. 

ANSI 

/* This example shows how you would abort a program */ 

/* if it is not called with a valid input file name. */ 

{{include <stdlib.h> 

{{include <stdio.h> 

void main(int argc, char *argv[J) 

{ 

FILE *f ; 

if (argc > 1 ) 

i 

f = fopen(argv[ 1 ] , "r" ) ; 
if (f == NULL) 

( 

fprintf ( stderr , 

"Can't open file \"JSs\"\n", 
argv [ 1 J ) ; 

exit ( EXIT-FAILURE ) ; 

J 

fclose( f ) ; 

) 
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exit Terminate program execution 
( continued ) 

else 

I 

fprintf (stderr, "No file specif ied\n" ) 
exit ( EXIT-FAILURE ) ; 

) 

) 

See Also longjmp 
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exit 

Synopsis 

Description 


Portability 
See Also 


Terminate program execution with no clean-up 
((include <stdlib.h> 

void exit (code) ; 

int code; 

This function terminates the current program immediately and returns 
control to the parent program. This function does not write output 
buffers or close level 2 files. Generally, this function is used only in 
emergency situations when you do not care if some output data are lost. 

Files opened with the open, creat, or creatx function are closed. 

The code parameter is a value from 0 to 255 that gets passed back to 
the parent. By convention, a value of 0 indicates success. 

From within a shared library, you must not call any library functions 
that terminate your program. For example, you cannot call exit, 

exit, or abort from a shared library. You also cannot use set jmp 

and long jmp to jump across a call from the program into the library. 

SAS/C 

exit 
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exp 

Synopsis 

Description 

Portability 

Returns 


Exponential function 
((include <math.h> 
r = exp(x); 
double r, x; 

The exp function raises the natural logarithm base e to the x power. A 
range error occurs if x is too large. 

ANSI 

This function returns a double-precision floating-point number containing 
the calculated exponential. 


See Also log, matherr 
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tabs 

Synopsis 

Description 

Portability 

Returns 

See Also 


Floating-point or double-precision floating-point absolute value 
Kinclude <math.h> 
ad = fabs (d) ; 
double ad,d; 

This function computes the absolute value of either a floating-point 
number or a double-precision floating-point number. Floating-point 
arguments are automatically promoted to double-precision floating-point 
arguments. 

ANSI 

This function returns a double-precision floating-point number containing 
the absolute value of the argument. 

abs 
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fclose 

Synopsis 


Description 


Portability 

Returns 

See Also 


Close a level 2 file 

((include <stdio.h> 

ret = fclose(fp); 

int ret; /* return code */ 

FILE *f p ; /* file pointer for file to be closed */ 

The fclose function completes the processing of a level 2 file and 
releases all related resources. If the file is in the course of being written, 
any data which have accumulated in the buffer are written to the file, and 

the level 1 close function is called for the associated file descriptor. 

The buffer associated with the file block is freed. 

Even though the fclose function is automatically called for all open 
files when your program terminates or calls the exit function, it is good 
programming practice to close your own files explicitly. The last buffer is 
not written until the fclose function is called, and data may be lost if 
an output file is not properly closed. 

ANSI 

If successful, the fclose function returns 0. This function returns EOF 
to indicate an error. If EOF is returned, additional error information can 
be found in the external integers err no and _OSERR. 

errno, fopen, open, _OSERR 
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fcloseall 

Synopsis 

Description 


Portability 

Returns 


Close all level 2 files 
{(include <stdio.h> 
num = f closeall( ) ; 

int num; /* number of files closed */ 

The fcloseall function closes all level 2 files that were open and 
returns that number. However, if an error occurs on any file, the 
fcloseall function continues to close the other files and then returns a 
value of —1. 

The fcloseall function closes the standard files stdin, stdout, 
and stderr. Functions such as printf and perror will fail after you 
call the fcloseall function. 

XENIX 

If successful, the fcloseall function returns the number of files that 
were closed. This function returns — 1 to indicate an error. If — 1 is 
returned, additional error information can be found in the external 
integers errno and_OSERR. 


See Also errno, f open, _OSERR 
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fcvt 

Synopsis 


Description 


Portability 

Returns 


Convert a floating-point number to a string 
Uinclude <math.h> 


s = fcvt(v, dig, decx, sign) ; 


char *s; 
double v; 
int dig; 
int *decx; 
int *sign; 


/* string pointer */ 

/* floating point value */ 

/* number of digits */ 

/* pointer to decimal index (returned) */ 
/* pointer to sign indicator */ 


This function converts a floating-point number into an ASCII character 
string consisting of digits only and terminated by a null character. 

The second argument, dig, indicates the total number of digits that 
should be generated If the floating-point value contains fewer significant 
digits, zeroes are appended. If there are too many significant digits, the 
low-order (right-most) digit is rounded. 

The decx argument points to an integer that receives a value 
indicating where the decimal point should be placed in the string. For 
example, an index value of 3 indicates that the decimal point should be 
placed just after the third character in the string. A value of 0 means that 
the decimal point is just before the first character. If the index is 
negative, it indicates the number of zeroes that are between the decimal 
point and the first character. For example, —3 means that there are 
three zeroes between the decimal point and the beginning of the string. 

The sign argument points to an integer that is nonzero if the value v 
is negative. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


UNIX 


This function returns a pointer to a string containing the ASCII 
representation of the float argument. 
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fcvl 

(continued) 

Example 


Convert a floating-point number to a string 


jfinclude <stdio.h> 

((include <math.h> 

void main(void) 

( 

int decx, sign; 
char *string; 

string = fvct(3. 1415926535, 10, 6decx , Ssign) ; 

/* string => "3141592654" */ 

/* decx => 1 */ 

/* sign => 0 */ 

printf ( "string = %s, decx = %d , sign = Xd\n" , 
string, decx, sign); 


See Also 


ecvt 
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fdopen Attach a level 1 file to level 2 


Synopsis # include <stdio.h> 

fp = fdopen(fh,mode) ; 


FILE *fp; 

/* 

file 

pointer */ 

int f h ; 

/* 

file 

handle */ 

const char *mode; 

/* 

access mode */ 


Description This function attaches a level 1 file to level 2. In other words, if you have 
used the open function to prepare a file for level 1 I/O processing, you 
can subsequently use level 2 I/O with that file after calling the fdopen 
function. The file handle is the value returned by the open function, and 
the access mode has the same form as described for the f open function. 

Portability UNIX 


Returns If the operation is successful, the function returns a file pointer other 
than NULL. If it is not successful, the function returns a NULL pointer 
and places error information in the external integers err no and 
_OS ERR. 

This function is not available if the _ STRICT—ANSI flag has been 
defined. 


See Also errno, f open, _OSERR 
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feof 

Synopsis 

Description 

Portability 

Returns 

See Also 


Check for a level 2 end-of-file 
((include <stdio.h> 
ret = feof ( fp) ; 

int ret; /* non-zero if condition is true */ 

FILE *fp; /* file pointer */ 

This function generates a nonzero value if the specified file pointer is at 
end-of-file. This function is implemented as a macro. Also, it does not 
check whether the f p argument is a valid file pointer. 

ANSI 

This function returns a nonzero value if the specified file pointer is at 
end-of-file. If not, this function returns a 0. 

f error 
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terror Check for a level 2 error 
Synopsis # include <stdio.h> 
ret = ferror(fp); 

int ret; /* non-zero if condition is true */ 

FILE *f p ; /* file pointer */ 

Description This function tests the error indicator for the file pointed to by the f p 
argument. This function is implemented as a macro. The terror 
function does not check whether the f p argument is a valid file pointer. 

Portability ANSI 

Returns The return value is 0 if no error has been set. If an error indicator was 
set, a nonzero value is returned. 

See Also clearerr, feof 
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fflush 

Synopsis 


Description 

Portability 

Returns 


Flush a level 2 output buffer 

ilinclude <stdio.h> 

ret = f f lush( fp) ; 

int ret; /* return code */ 

FILE *fp; /* file pointer */ 

The fflush function flushes the output buffer of the specified level 2 
file. That is, it writes the buffer if the file is opened for output and the 
buffer contains any pending data. 

ANSI 

If an error occurs, the return value is —1 (EOF). The appropriate error 
code is placed into the external integer err no, and additional 
information is placed in the external integer _OSERR. 


See Also errno, f close, fcloseall, flushall, f open, _OSERR 
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fgetc 

Synopsis 


Description 

Portability 

Returns 

See Also 


Get a character from a file 
((include <stdio.h> 
c = fgetc(fp) ; 

int c; /* return character or code */ 

FILE *fp; /* file pointer */ 

This function gets a single character from the specified level 2 file. 

In the case of an error, this function returns an EOF. To distinguish 
errors from an end-of-file condition, you should reset the external integer 
err no before calling the function, and analyze its contents when you 
receive an EOF return. 

ANSI 

If successful, the next input character is returned. Otherwise, the 
function returns EOF, which is defined in the file stdio .h. In the event 
of an EOF return, error information can be found in the external integers 
errno and_OSERR. 

errno, fgetchar, fopen, fputc, getc, getch, getchar, _OSERR, 
ungetc 



C Library Reference 223 


fgetchar 

Synopsis 

Description 


Portability 

Returns 


Get a character from stdin 
flinclude <stdio.h> 
c = fgetchar( void) ; 

int c; /* return character or code */ 

This function gets a single character from stdin. 

In the case of an error, this function returns an EOF. To distinguish 
errors from an end-of-file condition, you should reset the external integer 
err no before calling the function and analyze its contents when you 
receive an EOF return. 

This function is identical to fgetc(stdin). 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

XENIX 

If successful, the next input character is returned. Otherwise, the 
function returns EOF, which is defined in the stdio . h file. In the event 
of an EOF return, error information can be found in the external integers 
errno and_OSERR. 


See Also errno, f getc, f open, getc, getchar, _OSERR 
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fgetpos 

Synopsis 


Description 


Portability 

Returns 

Example 


Get the current file position 

({include <stdio.h> 

x = fgetpos(f , pos) ; 

int x; 

FILE *f ; 
fpos_t *pos ; 

The fgetpos function determines the current file position for the stream 
associated with the FILE object addressed by the f argument, and it 
stores the file position in the object pointed to by the pos argument. This 
object is of type fpos_t, which is defined in the stdio.h file. The 
stored value can be passed to the f setpos function to reposition the file 
to its position at the time of the call to the fgetpos function. 

The fgetpos function can be used with most types of files, using 
either text or binary access. 

ANSI 

If successful, the fgetpos function returns 0. If it fails, the fgetpos 
function returns a nonzero value and stores an appropriate error code in 
the external integer err no. See the description of the external integer 
errno in Chapter 6, “Predefined Data Name Reference,” for the list of 
err no values. 

In the following example, the function bldtable reads a file and builds 
a table of keys and record addresses. The function f indrec positions the 
file to the record with the required key using the f setpos function, and 
then it reads the record. 

((include <stdio.h> 

((include <string.h> 

((define KEYLEN 17 
jjdefine DATALEN 500 
((define TABSIZE 1000 

struct table { 

char keyval [KEYLEN] ; 
fpos_t location; 

} keytable[TABSIZE] ; 
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fgetpos Get the current file position 
(continued) 


struct record { 

char keyval [KEYLEN] ; 
char data[DATALEN] ; 

I; 


int filesize; 

/* Initialize keytable, which is a */ 

/* table of keys and locations */ 
void bldtable(FILE *fileptr) 

{ 

struct record input; 
int index =0; 

while ( !feof (fileptr) ) 

{ 

/* Store file pointer location */ 
fgetpos (fileptr, gkeytable] index] .location) ; 

/* Read 1 record */ 

fread( Sinput , sizeof ( struct record), 1, fileptr); 
if (feof (fileptr) II ferror( fileptr ) ) 
break; 

/* Save the keyval */ 

memcpy( keytable] index] .keyval, input. keyval, KEYLEN); 
index++; 

) 

filesize = index; 
return; 


/* Find a match in the file to the key, */ 

/* and return complete record. */ 

int findrec(FILE *fileptr, char keyval [KEYLEN ] , 
struct record *input) 

( 

int index; 
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fgetpos Get the current file position 
( continued ) 

/* Search keytable for specified value */ 
for (index = 0; index < filesize; ++index) 

if (memcmp(keyval, keytable [ index ] .keyval , KEYLEN) 
break; 

if (index >= filesize) 

return (-1); /* Keyval not found */ 

/* If found, read complete record from file */ 
fsetpos (fileptr, 6keytable[ index] .location) ; 
fread (input, sizeof (struct record), 1, fileptr); 
return (0); 

) 

See Also fseek, fsetpos, ftell, lseek 
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fgets 

Synopsis 


Description 

Portability 

Returns 

Example 


Get a string from a level 2 file 
Sinclude <stdio.h> 


p = fgets(buffer, length, fp) ; 


char *p ; 
char *buffer; 
int length; 
FILE *fp; 


/* buffer pointer or NULL */ 
/* buffer pointer */ 

/* buffer length in bytes */ 
/* file pointer */ 


The fgets function gets a string from the specified level 2 file, which 
must have been previously opened for input. Characters are copied from 
the file to the buffer until a new line (\n) has been copied, or length - 1 
characters have been copied, or the end-of-file is hit. In any case, the 
buffer is terminated with a trailing null byte (\0). 

ANSI 


If the end-of-file is hit before any bytes are read, a NULL pointer is 
returned. If an I/O error occurs, a NULL pointer is returned and 
additional information is placed in the external integers err no and 

OSERR. If no I/O error occurs and at least one byte was read from the 

file, the buffer argument is returned. 

/* Assume that stdin contains the following lines: */ 

/* */ 

/* Hello, folks! */ 

/* Goodbye, folks! */ 

finclude <stdio.h> 

void main(void) 

( 

char *p,b[ 80 ] ; 

/* For the next two lines, p will point to b */ 
p = fgets(b,sizeof(b) , stdin) ; 
printf("b = Xp, %sp = %p\n", b, b, p); 
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fgets Get a string from a level 2 file 
( continued ) 

/* b contains "Hello, folks!" */ 
p = fgets(b,sizeof (b) , stdin) ; 
printf("b = $p, $sp = Sp\n", b, b, p); 

/* b now contains "Goodbye, folks !\n" */ 
p = fgets(b,sizeof(b) , stdin) ; 
printf("b = %p , Ssp = Xp\n", b, b, p); 


See Also errno, feof, terror, fgetc, fopen, fread, getc, gets, _OSERR 
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fileno Get the file number for a level 2 file 

Synopsis Dinclude <stdio.h> 

fh = f ileno( fp) ; 

int fh; /* file handle */ 
FILE *fp; /* file pointer */ 


Description This function gets the file handle (the file number) associated with the 
specified file pointer. The file pointer must be one that was returned by 
the fopen, freopen, or fdopen function. 

This function is implemented as a macro. Also, it does not check that 
the fp argument is a valid file pointer. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability UNIX 

Returns The return value is an integer representing the file handle. 

See Also fdopen, fopen, freopen 
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findpath Locate a file in the current path 
Synopsis (f include <dos.h> 

lock = f indpath(filename) ; 

BPTR lock; 

const char *filename; 

Description This function locates a file in the currently defined path. If the process is 
not a Shell process, it uses the path in effect when Workbench was 
loaded. 

Portability AmigaDOS 

Returns If the findpath function finds the file, it returns a lock on that 

directory even if it is the current directory. The lock must be unlocked 
with the AmigaDOS UnLock function. If the findpath function cannot 
find the file, it returns a —1. The value NULL is not used because NULL 
is a valid lock. 

Example (f include <stdio.h> 

((include <stdlib.h> 

((include <dos.h> 

((include <proto/dos.h> 

((include <proto/exec.h> 

void main(int argc, char *argv[]) 

{ 

char path[ 256 ] ; 
long rc; 

BPTR lock; 

struct DosLibrary *D0SBase; 
rc = EXIT-FAILURE ; 

if {(DOSBase = (struct DosLibrary *) 

OpenLibrary( "dos . library" , OL)) == NULL) 

i 

printf ("Couldn't open dos . library ! \n" ) ; 

) 
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findpath Locate a file in the current path 
( continued ) 


else 

( 

if (argc < 2) 

{ 

printf("You must enter a file to find!\n"); 

} 

else 

{ 

printf ( "Looking for V'flsV... ", 
argv[ 1 ] ) ; 

if ((lock = f indpath(argv[ 1 ] ) ) == ( ( BPTR ) - 1 ) ) 

{ 

printf ("Error !\n" 

"Cannot find \"*s\" in " 

"the current path\n", argv [ 1 ] ) ; 

) 

else 

I 

printf ( "Found it!\n"); 
if (getpath( lock, path) == 0) 

{ 

printf ( "Path: \"fts\"\n", 
path) ; 

) 

UnLock( lock) ; 
rc = EXIT_SUCCESS; 


} 

CloseLibrary( (struct Library *)DOSBase); 

) 

exit(rc) ; 


See Also getpath, UnLock (The AmigaDOS Manual, 3rd Edition) 
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floor 

Synopsis 

Description 

Portability 

Returns 

Example 


Get the floor of a real number 
((include <math.h> 
x = f loor(y) ; 
double x,y; 

This function returns the largest integer not greater than the specified 
real number. 

ANSI 

The result is a real number. 

((include <stdio.h> 

((include <math.h> 

void main(void) 

( 

double r; 

r = floor(523.96) ; /* r contains 523.0 */ 

printf ( "floor(523.96) = Xlf\n", r); 

} 


See Also 


ceil 
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flushall 

Synopsis 

Description 

Portability 

Returns 

See Also 


Flush all level 2 output buffers 

finclude <stdio.h> 

num = f lushall( void) ; 

int num; /* number of open files */ 

The flushall function flushes all level 2 output buffers and returns the 
number of level 2 files that are open. If an error occurs, the function 
continues to flush the remaining files and then returns a value of —1. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

XENIX 

If an error occurs, the return value is —1 (EOF). The appropriate error 
code is placed into the external integer err no, and additional 
information is placed in the external integer _OSERR. 

errno, fclose, fcloseall, f flush, f open, _OSERR 
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fmod 

Synopsis 

Description 

Portability 

Returns 


Example 


Floating-point modulus operations 
((include <math.h> 
x = fmod ( y , z ) ; 
double x,y,z; 


The fmod function calculates the floating-point remainder of y/z. If the 
% (modulus) operation were defined for floating-point numbers, the 
expression would produce the following: 

x = y % z; 

ANSI 

This function returns the value y if the value z is 0. Otherwise, it 
returns a value that has the same sign as y, is less than z, and satisfies 
the following relationship: 

y = (i * z) + x 

The argument i is an integer. 

((include <stdio.h> 

((include <math.h> 

void main(void) 

{ 

double r; 

r = fmod(5.7, 1 . 5) ; /* r contains 1.2 */ 

printf ( "fmod( 5 . 7 , 1.5) = %lf\n", r); 

) 


See Also 


modf 
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fmode 

Synopsis 


Description 


Portability 
See Also 


Change the mode of a level 2 file 

((include <stdio.h> 

void fmode( fp,mode) ; 

FILE *fp; /* file pointer */ 
int mode; /* 0 => mode A */ 

/* 1 => mode B */ 

This function is used to change the translation mode of a level 2 file that 
has been opened with the fopen, f reopen, or fdopen function. 

In mode A, carriage returns are deleted on input, and a carriage return 
is inserted before each line feed on output. Mode A also detects the 
Control-Z character (Ox 1 A) as a logical end-of-file mark. In mode B, all 
data are transferred with no changes. 

For AmigaDOS, the default mode is B. 

The file pointer is not checked for validity. 

This function is not available if the _STRICT__ANSI flag has been 
defined. 

SAS/C 

fdopen, fopen, freopen 
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fopen Open a level 2 file 

Synopsis i include <stdio.h> 

fp = fopen(name, "mode" ) ; 

FILE *fp; /* file pointer */ 

const char *name; /* file name */ 

const char *mode; /* access mode string */ 

Description This function opens a file for buffered access. The name string can be any 
valid filename and may include a device code and directory path. The 
mode string specifies the values for each mode (Create, Trunc, Read, 
Write, Append, and Translate) with which you want to open the file. 

Note: Do not place the const keyword on the declarations for the 
name and mode arguments in your program. For information about the 
const keyword, see the description of the Synopsis section at the 
beginning of this chapter. 

The values of the modes Create, Trunc, Read, Write, Append, and 
Translate indicate how you want the file to be processed. The following 
table describes the effect of each setting of these modes. 


Mode 

Value 

Effect 

Create 

yes 

The file will be created if it does not already 
exist. 


no 

The function will fail if the file does not already 
exist. 

Trunc 

yes 

If the file exists, it will be truncated (marked as 
empty). 


no 

If the file exists, its current contents will not be 
disturbed. 

Read 

yes 

The file can be read with functions such as 
fread and fgetc. Also, the f seek function 
can be used to position the file before reading. 


no 

The file cannot be read. 


( continued ) 
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fopen Open a level 2 file 
(continued) 


Mode Value Effect 


Write yes 


no 


Append yes 


no 


Translate default 


The file can be written with functions such as 
f write and fputc. Also, the fseek function 
can be used to position the file before writing. 

The file cannot be written, but see Append 
below. 

The file can be written, but it is automatically 
positioned to the current end-of-file before each 
write operation. This mode prevents existing 
data from being changed. 

Automatic positioning to the end-of-file is not 
done before a write operation. Also, writes are 
not allowed unless the Write mode value is 
Yes. 

The external integer fmode is used to set 

mode A or mode B as follows: 


if ( fmode S 0 x 8000 ) 

set mode B 
else set mode A 

For AmigaDOS, the external integer fmode 

is normally 0x8000. 

mode A On a read operation, each carriage-return 
character (\r) is deleted, and the Control-Z 
character is treated as a logical end-of-file mark. 
On a write operation, each line-feed character 
(\n) is expanded to a carriage return followed 
by a line feed. 

mode B The data are unchanged as they are read or 
written. 
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fopen Open a level 2 file 
( continued ) 

The following table shows the list of values specified by each mode string. 


Mode 

String Create Trunc Read Write Append Translate 


r 

no 

no 

yes 

no 

no 

default 

w 

yes 

yes 

no 

yes 

no 

default 

a 

yes 

no 

no 

no 

yes 

default 

r + 

no 

no 

yes 

yes 

no 

default 

w+ 

yes 

yes 

yes 

yes 

no 

default 

a+ 

yes 

no 

yes 

no 

yes 

default 

ra 

no 

no 

yes 

no 

no 

mode A 

wa 

yes 

yes 

no 

yes 

no 

mode A 

aa 

yes 

no 

no 

no 

yes 

mode A 

ra + 

no 

no 

yes 

yes 

no 

mode A 

wa + 

yes 

yes 

yes 

yes 

no 

mode A 
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If the file is successfully opened, the function returns a pointer to a 
buffered I/O control block, which is defined in the header file stdio . 
Normally, you will not need to access any information in the control 
block directly, but you should be very careful not to disturb the block 
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(continued) 


Portability 


Returns 


Example 


Open a level 2 file 


accidentally. A common C programming error is to accidentally mutilate 
one of these control blocks, which can cause garbage to be written into a 
file. 

ANSI 

Mode A open modes are an extension to the ANSI standard, and you 
should not use them in programs that you want to be ANSI-compatible. 

A NULL pointer is returned if the file cannot be opened. Consult the 
external integers err no and_OSERR for detailed error information. 

When a file is opened for both reading and writing, you should call the 
fseek or rewind function when switching from reading to writing or 
vice-versa. It is not necessary to do this when you begin writing after 
reading up to the end of the file. 

/* This is an example of using fopen to write a copy */ 

/* file routine. It returns 0 if the file copy was */ 

/* successful; otherwise, it returns a -1. */ 

iinclude <stdio.h> 
copy ( infile, outfile) 

char *infile,*outfile; /* input and output file names */ 

( 

FILE *in,*out; 
char buf [ 100] ; 
int i ; 

/* open the input file */ 
if ( ( in=fopen( inf ile, "r" ) )==NULL) 
return(-1 ) ; 

if ( (out=fopen(outfile,"wt") )==NULL) 

{ 

fclose( in) ; 
return(-1 ) ; 

} 

/* copy the file contents */ 
while ( i = fread( buf , 1 , 1 0 0 , in ) ) 
if ( fwrite(buf , 1 , i,out) !=i) 
break; 
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/* now set up the return */ 
i=( terror (in) I I terror (out) ) ?— 1 :0; 

/* close the files */ 
fclose( in) ; 
fclose(out) ; 
return( i ) ; 

) 

See Also f close, fdopen, fgetc, fgets, fputc, fputs, tread, f reopen, 
fwrite, open 
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forkl, forkv Create a child process with an argument list or vector 
Synopsis # include <dos.h> 

error = forkl ( prog, argO , argl , . . . ,argn,NULL,env,procid) ; 
error = forkv(prog,argv,env,procid) ; 

cc = wait(procid) ; 
complist = waitm(proclist) ; 


int error; 
char *prog; 
char *argO; 
char *arg1; 
char *argn; 
char *argv[ ] 


/* error code */ 

/* program name */ 

/* argument # 0 */ 

/* argument §1 */ 

/* argument |fn */ 

/* argument vector */ 


struct FORKENV *env; /* pointer to pseudo environment*/ 

/* structure (may be NULL)*/ 

int cc; 

struct ProcID *procid; /* pointer to process ID structure*/ 

struct ProcID **proclist; /* address of pointer to linked*/ 

/* list of process IDs*/ 

struct ProcID *complist; /* pointer to linked list of*/ 

/* completed process IDs*/ 


Description The forkl and forkv functions create a child process by loading a new 
program as a concurrent process. The parent continues to execute until it 
calls either the wait or waitm function; that is, the parent and child are 
multiprogrammed. When the child process completes, the parent process 
(the current program) can get its completion code with the wait or 
waitm function. 

To specify the arguments for the new program with the forkl 
function, specify a list of argument string pointers terminated by a NULL 
pointer (argO , arg , argn , NULL). To specify the arguments with 

the forkv function, specify a single pointer (argv) to an array of 
argument string pointers, with the array being terminated by a NULL 
pointer. Following UNIX conventions, the first argument (argO or 
argv [ 0 ] ) should be the program name and is normally the same as the 
prog argument. Under AmigaDOS, the arguments are all concatenated 
into a pseudo-command line, with a blank separating adjacent arguments 
and a carriage-return character at the end. The maximum size of this line 
is 255 bytes. 
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forkl, forkv Create a child process with an argument list or vector 
(continued) 


The pseudo-environment pointer env, if specified, contains optional 
data about default files and process execution. The FORKENV structure is 
defined in the file dos . h and has the following format: 


Struct FORKENV { 
long priority; 
long stack; 
BPTR std_in; 
BPTR std_out; 
BPTR console; 
struct MsgPort 

}; 


/* new process priority */ 

/* stack size for new process */ 

/* stdin file handle for new process */ 
/* stdout file handle for new process */ 
/* console window for new process */ 

♦msgport; /* msg port to receive */ 

/* termination msg from child */ 


The child process is supplied with default values for any field left null. 
In addition, a NULL pointer may be passed for this parameter, which 
causes default values to be used for all items. If the default values are 
used, the child process is created with a priority of 0, a stack size of 
8000 bytes, the current stdin and stdout files, and console for the 
parent process, and a new message port is created to receive the 
termination message. 

The new process executes as a CLI-type task. This means it will be 
expecting file handles for stdin and stdout to be present, and a 
console task handler to exist. If the parent process is running as a 
Workbench process then it is possible for none of these to exist for the 
child process to inherit. If the parent process can be invoked from 
Workbench, extra effort should be made to ensure the presence of file 
handles the child may require. These file handles are BPTR values, as 
returned by the AmigaDOS open call. 

The optional message-port field is provided to allow the parent process 
to detect when a child process has terminated while awaiting other 
events, such as Intuition menu events. The termination message format is 
similar to an Intuition message. The TermMsg structure is defined in the 
dos/dos.h file and has the following format: 

struct TermMsg { 

struct Message msg; /* termination message from child */ 
long class; /* class == 0 */ 
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forkl, forkv 

(continued) 


Create a child process with an argument list or vector 


short type; /* 
struct Process *process; /* 
long ret; /* 


message type == 0 */ 
process ID of sending task */ 
return value */ 


When a termination message is received, the parent process must still 
call the wait function to remove the message and unload the child 
process. If the message was removed from the port, it must be replaced 
by calling the PutMsg function before calling the wait function. 

The forkl function loads the program from the current path using the 
AmigaDOS search procedure. If the calling program was loaded from the 
Workbench, the path used is the path at the time the Workbench was 
loaded. Alternatively, you can include a path specification as part of the 
program name. 

Upon successful creation of the child process, the forkl function fills 
in the process ID structure. The address of this structure must be passed 
as the last argument. The process ID structure is defined in the dos . h 
file and has the following format: 


struct ProcID ( /* 

struct ProcID *nextID; /* 
struct Process *process; /* 
int UserPortFlag; 
struct MsgPort *parent; /* 
struct MsgPort *child; /* 
BPTR seglist; /* 

}; 


packet returned from fork */ 
link to next packet */ 
process ID of child */ 

termination msg destination */ 
child process' task msg port */ 
child process' segment list */ 


The next ID field may be used to link process ID structures into a 
simple linked list for use with the waitm function. The process field is 
the address of the process’s task structure and is the value used with 
ROM Kernel functions, such as the signal function, that require a task 
ID parameter. The remaining fields are used by the wait function. 

The wait or waitm function must be called for each child process to 
ensure that the child process terminates cleanly. The wait function takes 
as its single argument a pointer to the ProcID structure for the child 
task. It waits for a termination message from one particular process, 
replying to and discarding any other messages that arrive at the message 
port. The function returns the child process’s completion code. This is the 
value that was passed to the exit function when the child terminated. 
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forkl, forkv 

( continued ) 


Portability 

Returns 


Example 


Create a child process with an argument list or vector 


If any child processes share a message port, however, then the waitm 
function should be called to ensure that no termination messages are lost. 
The waitm function requires the address of a pointer to the first 
ProcID structure in a linked list of child process ProcID structures. It 
waits for one or more termination messages, removing the ProcID 
structure from the original linked list and inserting it into a linked list of 
terminated process ProcID structures. The completion code is placed in 
the UserPortFlag field of the structure. The function then returns a 
pointer to the first structure in the list of terminated process structures. 
Since the original list is updated, it may be reused to wait for the 
remaining child processes. 

The wait or waitm function must be called for each child process 
before terminating the parent process. Otherwise, the child process will 
never be unloaded, and there is an excellent possibility that the system 
will crash. 

Note: BCPL programs cannot be executed using the forkl or forkv 
function. These programs include all of the AmigaDOS routines under 
Workbench 1.3. The AmigaDOS routines from Workbench 2.0 will fork 
properly. 

SAS/C 

If the specified program file cannot be found, a — 1 return is made, and 
additional error information can be found in the external integers err no 
and _OSERR. You must call the wait function to obtain the completion 
code from the child process. 

The following program, child . c, creates a child process. 

/* This program creates a child process and displays */ 

/* the return code. The child program name and */ 

/* arguments are taken from the command line. */ 

((include <stdio.h> 

((include <stdlib.h> 

((include <dos.h> 


struct ProcID child; 
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(continued) 


Create a child process with an argument list or vector 


void main(int argc, char *argv[]) 

( 

int ret; 
if (argc < 2) 

( 

printf("no program specif ied\n" ) ; 

printf( "usage: fork program ( arg 1 ] ... [argn]\n" 

exit ( EXIT-FAILURE ) ; 

) 


printf ( "parent: beginning fork of fts\n" ,argv( 1 ] ) ; 
if (forkv(argv[ 1 ] ,6argv[ 1 ] , NULL , S chi Id) == -1) 

{ 

printf ( "error forking child\n"); 
exit (EXIT-FAILURE) ; 

} 

else 

( 

ret = wait( Schild) ; 

} 

printf ( "parent : £s finished, ret = Xd\n" ,argv( 1 ] ,ret) ; 


The following program, parent.c, forks multiple child processes. 

/* This example forks multiple child processes */ 

((include <stdio.h> 

((include <stdlib.h> 

((include <dos.h> 

char *child1_argv[ ] =("task1" , /* program name */ 

"argumentl", /* 1st argument */ 

"argument2", /* etc., etc. */ 

NULL) ; 
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( continued ) 


Create a child process with an argument list or vector 


char 

*child2_argv[ ] 

={"task2", 

/* 

program name 

*/ 



"arguraentl", 

/* 

1st argument 

*/ 



"argument 2" , 
NULL ) ; 

/* 

etc., etc. 

*/ 

char 

*child3_argv[ ] 

= ( "task3" , 

/* 

program name 

*/ 



" argument 1 " , 

/* 

1st argument 

*/ 



"argument2" , 

/* 

etc., etc. 

*/ 


NULL ) ; 

void main(void) 

{ 

struct ProcID *children, *terminated, *task; 
struct ProcID childl, child2, child3; 
int taskno; 

if (forkv(child1_argv[0] ,child1_argv,NULL, Schildl ) = 

{ 

printf ("error forking childl \n"); 
exit ( EXIT-FAILURE ) ; 

} 

if (forkv(child2_argv[0) ,child2_argv,NULL, Schild2) = 

( 

printf ( "error forking child2\n"); 
exit (EXIT-FAILURE) ; 

} 

if (forkv(child3_argv[0] ,child3_argv,NULL,Schild3) = 

{ 

printf ( "error forking child3\n"); 
exit ( EXIT-FAILURE ) ; 

} 

child3 .nextID = NULL; 
child2 .nextID = Schild3; 
childl .nextID = Schild2; 


children = Schildl ; 
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(continued) 

while(children) /* wait until no more children */ 

( 

/* must pass ADDRESS of pointer */ 
terminated = waitm( ^children) ; 

for (task = terminated; task != NULL; task = task->nextID) 

( 

if (task == 6 child 1 ) 

{ 

taskno = 1; 

) 

else if (task == 5child2) 

{ 

taskno = 2; 

) 

else if (task == Schild3) 

{ 

taskno = 3; 

) 

printf("task jsd terminated, value = 5Sd\n", 
taskno, task->UserPortFlag) ; 

} 

) 


See Also exit, wait, waitm; LoadSeg, CreateProc, Execute, System, and 
Open in The AmigaDOS Manual, 3rd Edition 
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fprintf Formatted print 
Synopsis # include <stdio.h> 


length = fprintf ( fp, fmt,arg1 ,arg2, ...) ; 

int length; /* number of characters generated */ 

FILE *f p ; /* file pointer */ 

const char *fmt; /* format string */ 

type *argn; /* arguments */ 

Description This function produces an output stream of ASCII characters, and sends 
the output to the level 2 file specified by the fp argument. 

The fmt argument points to a string that contains ordinary characters 
and conversion specifications that indicate how you want the arguments 
argl, arg2, and so on to be printed. The ordinary characters are copied 
to the output, but the conversion specifications are replaced with the 
correctly formatted values of the arguments argl, arg2, and so on. The 
first conversion specification is replaced with the formatted value of 
argl, the second specification is replaced with the value of arg2, and so 
on. In some cases, as described below, a conversion specification may 
process more than one argument. 

Each conversion specification must begin with a percent character (%). 
To place an ordinary percent into the output stream, precede it with 
another percent in the fmt string. That is, %% will send a single percent 
character to the output stream. A specification has the following format: 

%[flags][width][.precision][size]type 

The brackets ([]) indicate optional fields. Each field is defined as follows: 

flags controls output justification and the printing of signs, blanks, 
decimal places, and hexadecimal prefixes. 

If any flag characters are used, they must appear after the 
percent. Valid flags are as follows: 

- (minus) causes the result to be left-justified within the 
field specified by width or within the default 
width. 

+ (plus) causes a plus or minus sign to be placed before 
the result. This flag is used in conjunction with 
the various numeric conversion types. If it is 
absent, the sign character is generated only for a 
negative number. 



C Library Reference 249 


fprintf Formatted print 
( continued ) 


blank causes a leading blank for a positive number and 
a minus sign for a negative number. This flag is 
similar to the plus. If both the plus and the blank 
flags are present, the plus takes precedence. 

# (pound) causes special formatting. With the o, x, and X 

types, the pound flag prefixes any nonzero output 
with 0, Ox, or OX, respectively. With the f , e, 
and E conversion types, the pound flag forces the 
result to contain a decimal point. With the g and 
G types, the pound flag forces the result to 
contain a decimal point and retain trailing zeroes. 

0 (zero) pads the field width with leading zeros instead of 
spaces for the d, i, o, u, x, X, e, E, f , g, and G 
conversion types. If the minus flag is also used, 
the zero flag is ignored. If a precision is 
specified, the zero flag is ignored for conversion 
types d, i, o, u, x, and X. Behavior of the zero 
flag is undefined for the remaining conversion 
types. 

width specifies the held width, which is the minimum number of 
characters to be generated for this format item. 

The width is a nonnegative number that specifies the 
minimum field width. If fewer characters are generated by the 
conversion operation, the result is padded on the left or right 
(depending on the minus flag described above). A blank is 
used as the padding character unless width begins with a zero. 
In that case, zero padding is performed. If the minus flag 
appears, padding is performed with blanks, width specifies the 
minimum field width, and it will not cause lengthy output to 
be truncated. Use the precision specifier for that purpose. 

If you do not want to specify the field width as a constant 
in the format string, you can code it as an asterisk (*), with or 
without a leading zero. The asterisk indicates that the width 
value is an integer in the argument list. See the examples for 
more information on this technique. 

precision specifies the held precision, which is the required precision of 
numeric conversions or the maximum number of characters 
to be copied from a string, depending on the type field. 
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(continued) 


The meaning of the precision item depends on the field 
type, as follows: 


Type Meaning 

c The precision item is ignored, 

d, i, o, u, x, x The precision is the minimum 

number of digits to appear. If fewer 
digits are generated, leading zeroes 
are supplied. 

e * E * f The precision is the number of digits 

to appear after the decimal point. If 
fewer digits are generated, trailing 
zeroes are supplied. 

G The precision is the maximum 

number of significant digits, 
s The precision is the maximum 

number of characters to be copied 
from the string. 


As with the width item, you can use an asterisk for the 
precision to indicate that the value should be picked up from 
the next argument. 

size can be either L for long double, 1 for large size, or h for 

small size. When used with the d, i, o, u, x, or X conversion 
specifiers, h and 1 select argument types of short * and 
long *, respectively. When used with the e, E, f , g, or G 
conversion specifiers, the L specifies a long double argument 
instead of a double. 

type specifies the type of argument conversion to be done. Valid 
conversion types are as follows: 

c specifies single-character conversion. The associated 
argument must be an integer. The single character in the 
right-most byte of the integer is copied to the output, 
d specifies decimal-integer conversion. The associated 

argument must be an integer, and the result is a string of 
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digits preceded by a sign. If the plus and blank flags are 
absent, the sign is produced only for a negative integer. If 
the large size modifier is present, the argument is taken 
as a long integer. 

e specifies double-precision floating-point conversion. The 
associated argument must be a double-precision floating- 
point number, and the result has the form: 

—d.dde—ddd 

d is a single decimal digit, dd is one or more digits, and 
ddd is an exponent of at least two digits. The first minus 
sign is omitted if the floating-point number is positive, 
and the second minus sign is omitted if the exponent is 
positive. The plus and blank flags dictate whether there 
will be a sign character emitted if the number is positive. 
The number of digits before the decimal point depends on 
the magnitude of the number, and the number after the 
decimal point depends on the requested precision. The 
value is rounded to the specified number of digits. If no 
precision is specified, the default is six decimal places. 

E specifies double-precision floating-point conversion. This 
is exactly the same as type e except that the result has 
the form: 

— d.ddE—ddd 

f specifies double-precision floating-point conversion. The 
associated argument must be a double-precision floating- 
point number, and the result has the form: 

-dd.dd 

dd indicates one or more decimal digits. The minus sign 
is omitted if the number is positive, but a sign character 
will still be generated if the plus or blank flag is present. 
The number of digits before the decimal point depends on 
the magnitude of the number, and the number after the 
decimal point depends on the requested precision. If no 
precision is specified, the default is six decimal places. If 
the precision is specified as 0, or if there are no nonzero 
digits to the right of the decimal point, then the decimal 
point is omitted unless the pound (#) flag is specified. 
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( continued ) 


g specifies double-precision floating-point conversion 
(general form). The associated argument must be a 
double-precision floating-point number, and the result is 
in the e or f format, depending on which gives the most 
compact result. The e format is used only when the 
exponent is less than —4 or greater than the specified or 
default precision. Trailing zeroes are eliminated, and the 
decimal point appears only if any nonzero digits follow it. 

G specifies double-precision floating-point conversion 
(general form). This is identical to the g format, except 
that the E type is used instead of the e type. 

i specifies decimal-integer conversion. The associated 

argument must be an integer, and the result is a string of 
digits preceded by a sign. If the plus and blank flags are 
absent, the sign is produced only for a negative integer. If 
the large size modifier is present, the argument is taken 
as a long integer. 

n specifies the argument will be a pointer to an integer into 
which is written the number of characters written so far 
by this call to the fprintf function. If the large size flag 
is on, the argument must be a pointer to a long integer. If 
the small size flag is on, the argument must be a pointer 
to a short integer. 

o specifies octal-integer conversion. The associated 
argument is taken as an unsigned integer, and it is 
converted to a string of octal digits. If the large size 
modifier is present, the argument must be a long integer. 

p specifies pointer conversion. The associated argument is 
taken as a data pointer, and it is converted to 
hexadecimal representation. Under AmigaDOS, the 
pointer is printed as 8 hexadecimal digits, with leading 
zeroes if necessary. 

P specifies pointer conversion. This is the same as the p 
format, except that uppercase letters are used as 
hexadecimal digits. This conversion type is an extension 
to the ANSI standard. Do not use this extension if you 
want your program to be ANSI-compatible. 
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s specifies string conversion. The associated argument must 
point to a null-terminated character string. The string is 
copied to the output, but the null byte is not copied. 

u specifies unsigned decimal integer conversion. The 

associated argument is taken as an unsigned integer, and 
it is converted to a string of decimal digits. If the large 
size modifier is present, the argument must be a long 
integer. 

x specifies hexadecimal-integer conversion. The associated 
argument is taken as an unsigned integer, and it is 
converted to a string of hexadecimal digits with lowercase 
letters. If the large size modifier is present, the argument 
is taken as a long integer. 

x specifies hexadecimal-integer conversion. This is the same 
as the x format, except that uppercase letters are used as 
hexadecimal digits. 

Portability ANSI 

Returns This function returns the number of output characters generated. If an 
error occurs, the fprintf function returns a negative value and places 
additional information in the external integers err no and _OSERR. 

Example /* This example prints a message indicating whether */ 

/* the function argument is positive or negative. */ 

/* In the second printf, the width and precision */ 

/* are 15 and 8, respectively. */ 

((include <stdio.h> 

((include <math.h> 

void pneg(double value) 

I 

char *sign; 

if (value < 0) 

( 

sign = "negative"; 

) 


else 
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( 

sign = "not negative"; 

) 

fprintf (stdout, "The number %E is %s. \n", value, sign) ; 
fprintf (stdout, "The number %*.*E is %s.\n", 15, 8, value, sign) 


void main(void) 

{ 

pneg(37.8); 
pneg (-18.2) ; 

) 

See Also errno, f scant, _OSERR, printf, scant, sprintf, sscanf 
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fputc 

Synopsis 


Description 

Portability 

Returns 

See Also 


Put a character to a level 2 file 

Ifinclude <stdio.h> 

r = fputc(c, fp) ; 

int r; /* EOF or c */ 

int c; /* character to be output */ 

FILE *fp; /* level 2 file pointer */ 

This function puts a single character to the specified level 2 file. 

ANSI 

If successful, this function returns the character c; otherwise, it returns 
EOF. For disk files, an EOF return usually means that the disk is full. 
However, this type of return can also occur if the device is write- 
protected or if a write error occurs. In any case, additional error 
information can be found in the external integers err no and _OSERR. 

errno, fopen, fputchar, _OSERR, putc, putchar 
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fputchar 

Synopsis 


Description 

Portability 

Returns 

See Also 


Put a character to stdout 

((include <stdio.h> 

r = fputchar(c) ; 

int r; /* EOF or c */ 

int c; /* Character to be output */ 

This function puts a single character to stdout. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

XENIX 

If successful, this function returns the character c; otherwise, it returns 
EOF. For disk files, an EOF return usually means that the disk is full. 
However, this type of return can also occur if the device is write- 
protected or if a write error occurs. In any case, additional error 
information can be found in the external integers err no and _OSERR. 

errno, fopen, fputc, _OSERR, putc, putchar 
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f puts Put a string to a level 2 file 
Synopsis # include <stdio.h> 
error = fputs(s,fp) ; 


int error; 
const char *s; 
FILE *f p ; 


/* non-zero if error */ 
/* string pointer */ 

/* file pointer */ 


Description The fputs function writes the string s to a level 2 file that was 

previously opened for output. The string must be terminated by a null 
byte, which is not written. 

Portability ANSI 

Returns If an error occurs, the return value is EOF; otherwise, it is 0. Additional 
error information can be found in the external integers err no and 
OS ERR. 


Example /* This example writes the following two lines to stdout: */ 
/* */ 
/* This is the first line */ 

/* This is the second line 


((include <stdio.h> 

void main(void) 

( 

puts("This is the first line"); 
fputs ("This is ", stdout); 
puts ("the second line"); 

) 


See Also errno, terror, fopen, fputc, puts 
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fqsort Sort an array of floating-point numbers 
Synopsis ((include <stdlib.h> 


void fqsort(fa,n) ; 

float *fa; /* pointer to float array */ 
stze_t n; /* number of elements in array */ 

Description The fqsort function sorts the specified array of floating-point numbers 
using the ACM 271 algorithm, more popularly known as Quicksort. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability SAS/C 

Returns This function returns a void. 


See Also 


dqsort, lqsort, qsort, sqsort, tqsort 
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f read Read and write blocks 
Synopsis § include <stdio.h> 

a = fread(b, bsize, n, fp) ; 

size_t a; /* actual number of blocks */ 

void *b; /* pointer to first block */ 

size_t bsize; /* size of block in bytes */ 

size_t n; /* maximum number of blocks */ 

FILE *fp; /* file pointer */ 

Description This function uses level 2 1/0 operations to read blocks of data. Each 

block contains bsize bytes and up to n blocks are stored into contiguous 
memory locations beginning at location b. 

Blocks are read until n blocks have been stored or until the end-of-file 
is hit. If the end-of-file is hit in the middle of a block, that partial block 
will be stored in the b array, but it will not be included in the function 
return value. In other words, the return value indicates the number of 
complete blocks that were read. 

Portability ANSI 

Returns This function returns the number of complete blocks that were read. 

See Also fclose, feof, ferror, fgetc, fopen, fputc, fseek, fwrite 
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free 

Synopsis 

Description 


Portability 

Example 


Free memory 
({include <stdlib.h> 
void free(b) ; 

void *b; /* block pointer */ 

The free function releases a block of memory that was previously 
obtained using the calloc, malloc, or realloc function. For 
compatibility with some versions of UNIX, the block is not actually 
returned to the free space pool until the next time you call the calloc, 
malloc, realloc, or free function. Then, if that next call is to the 
realloc function and the block being reallocated is the one that was 
just freed, the realloc function will proceed correctly. In other words, 
you can ask the realloc function to reallocate a block that was freed as 
long as you have not called the calloc, malloc, or realloc function 
in the meantime. 

ANSI 

((include <stdio.h> 

((include <stdlib.h> 

((include <string.h> 

struct LIST 

( 

struct LIST *next ; 
char text [ 2] ; 

1 ; 


void main(int argc, char *argv[]) 

{ 

struct LIST *p ; 
struct LIST *q; 
struct LIST list; 
char b[ 256 ] ; 
int x; 
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free Free memory 
(continued) 


printf ( "\nBegin new group. .. \n" ) ; 
for (q = filist; ; q = p) 

{ 

printf ( "Enter a text string: "); 
if (fgets(b,sizeof (b) ,stdin) == NULL) 

I 

break; 

} 

if (b[ 0 ] == NULL) 

{ 

if (q == Slist) 

{ 

printf ("\n") ; 
exit ( EXIT_SUCCESS ) ; 

} 

break; 

) 

x = sizeof ( struct LIST) - 2 + strlen(b) + 1; 
p = (struct LIST *)malloc(x); 
if (p == NULL) 

( 

printf ("No more memory\n"); 
exit (EXIT-FAILURE) ; 

) 

q->next = p; 
p->next = NULL; 
strcpy(p->text, b); 


printf ( "\n\nTEXT LIST...\n"); 
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free Free memory 
(continued) 


/* 

* You must be sure to copy the next pointer from 

* the current block before you free it. Some 

* systems rely on a side-effect to be able to 

* access the memory after it is freed — this is 

* BAD PROGRAMMING PRACTICE! 

*/ 

p = list. next; 
while(p ! = NULL) 

( 

q = p->next; 
printf (p->text) ; 
free( (char *)p) ; 

p = q; 

) 

list. next = NULL; 


See Also calloc, getmem, malloc, rbrk, realloc, rlsmem, sbrk 
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freopen Reopen a level 2 file 
Synopsis flinclude <stdio.h> 

fpr = freopen(name, mode, f p ) ; 


FILE *fpr ; 
const char *name; 
const char *mode; 
FILE *fp; 


/* file pointer after re-opening */ 
/* file name */ 

/* access mode */ 

/* current file pointer */ 


Description This function reopens a level 2 file. That is, it attaches a new file to a 
previously used file pointer. The previous file is automatically closed 
before the file pointer is reused. The name and mode arguments are the 
same as those for the f open function. 


Portability ANSI 

Returns If successful, this function returns the file pointer. 

Check the return code for the value NULL; the same errors as defined 
for the f open function may occur. Also, for complete portability, do not 
assume that the fpr and f p pointers are identical. Use the fpr pointer 
to access the reopened file, not the fp pointer. 


See Also fdopen, f open 
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frexp 

Synopsis 

Description 

Portability 

Returns 

See Also 


Split floating-point value 

Hinclude <raath.h> 

f = frexp(v,xp); 

double f; /* fraction */ 

double v; /* value */ 

int *xp; /* exponent pointer */ 

The frexp function splits the floating-point value v into its fraction 
(mantissa) and exponent parts. 

ANSI 

This function returns the mantissa as a double-precision floating-point 
number whose absolute value is greater than or equal to 0.5 and less 
than 1.0. The exponent is returned as an integer whose absolute value 
less than 1024. If the value v is 0, both returned values will be 0. 

fmod, ldexp, matherr, modf 
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fscanf 

Synopsis 


Description 


Formatted input conversions 
iinclude <stdio.h> 
n = f scant ( fp, fmt, argl ,arg2, ...) ; 

int n; /* number of input items matched, or EOF */ 

FILE *fp; /* file pointer (fscanf only) */ 

const char *fmt; /* format string */ 

type *argx; /* pointers to input data areas */ 

This function reads formatted input from the specified level 2 file, fp. 
The input characters are read and checked against the format string, 
which may contain any of the following: 

white space 

Any number of spaces, horizontal tabs, or new-line characters cause 
input to be read up to the next character that is not white space, 
ordinary characters 

Any character that is not white space and is not the percent sign (%) 
must match the next input character. If there is not an exact match, 
scanning stops, and the function returns, 
conversion specification 

This is a multicharacter sequence that indicates how the next input 
characters are to be converted. The following paragraphs describe this 
conversion specification. 

The conversion specification follows this format, where brackets ([]) 
indicate an optional part: 

%[*][n][l | h]t 

The various fields are defined as follows: 

% introduces a conversion specifier. If you want to match a percent 
sign in the input, use a double percent (%%) in the format string. 

* means that the conversion should be performed, but the result 
should not be stored. You should not specify a pointer for any 
conversion specification that uses the asterisk (*) to suppress 
conversion. 

n specifies the maximum input field width and should be a decimal 
number. This is used only with the s format. 

1 indicates that a long integer conversion should be performed. If 
neither 1 nor h is specified, the default is an integer. 
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fscanf Formatted input conversions 
( continued ) 

h indicates that a short conversion should be performed. If neither 1 
nor h is specified, the default is an integer. 
t stands for one of the following format characters: c, d, e, f, g, i, n, 
o, s, u, x, and [ ]. These characters specify how the input 
characters are to be converted. 

The following list describes each of the format characters. 

c specifies character conversion. The corresponding argument must 
point to a character. The next input character is moved to that 
destination. No white space is skipped. 

d specifies decimal number conversion. The corresponding 

argument must point to an integer or to a long integer if the d is 
preceded by an 1. The input characters should be decimal digits 
and may be preceded by a plus or minus sign. 

e,f ,g specifies floating-point conversion. These three types are identical. 
The corresponding argument must point to a floating-point 
number or to a double-precision floating-point number if the type 
letter is preceded by an 1 . The input characters must follow this 
format, where brackets ([]) indicate an optional part: 

[whitespace][sign]digits[.digits][exponent] 

1. leading white space 

2. a plus (+) or minus ( — ) sign 

3. a sequence of decimal digits 

4. a decimal point followed by 0 or more decimal digits 

5. an exponent, consisting of the letter e or E followed by an 
optional plus or minus sign followed by one or more 
decimal digits 

n indicates a character count. No input characters are read. The 
corresponding argument must point to an integer into which is 
written the number of input characters read so far. 
o indicates an octal number. The corresponding argument should 
point to an integer, or to a long integer if the o is preceded by an 
1 . 

s indicates a character string. The corresponding argument should 
point to a character array large enough to hold the string and a 
terminating null byte. The input string is terminated by white 
space or the end-of-input. Also, if a maximum field width is 
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fscanf Formatted input conversions 
(continued) 

specified, the output array size should be at least that width plus 
1 because the reading of input characters will stop at the field 
width even if no white space has been encountered, 
u indicates an unsigned integer. The corresponding argument 
should point to an unsigned integer or to an unsigned long 
integer if the u is preceded by an 1. 
x indicates a hexadecimal integer. The corresponding argument 
should point to an integer or to a long integer if the x is 
preceded by an 1. The hexadecimal number can begin with the 
characters Ox or OX, and case is not significant for the 
hexadecimal letters. 

[ ] indicates a string comprised of a specific set of characters. A 
terminating null character is automatically added. The 
corresponding argument should point to an array large enough to 
hold the sequence plus the terminating null character. 

Except for the c and [ ] specifiers, white space characters in the 
format string cause white space characters in the input to be skipped. 

If the conversion is successful and the assignment is not suppressed, 
the result is placed into the corresponding argument. The argument list 
must contain a pointer to an appropriate data item for each conversion 
specification that does not suppress assignment. 

Portability ANSI 

Returns The function returns the number of assignments that were made. For 
example, a return value of 3 indicates that conversion results were 
assigned to the arguments argl, arg2, and arg3. The number of 
assignments can be less than the number expected if the input characters 
do not agree with the format string. If an end-of-input is reached before 
any values are assigned, the return value is EOF. 


See Also 


scanf, sscanf 
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fseek Set a level 2 file position 
Synopsis # include <stdio.h> 

error = f seek( fp, rpos ,mode ) ; 


int error; 

FILE *fp; 
long int rpos; 
int mode; 


/* non-zero if error */ 

/* file pointer returned from fopen() */ 
/* relative file position */ 

/* seek mode */ 


Description The fseek function moves the byte cursor of a level 2 file to a new 
position. The mode argument must be one of the following: 

SEEK SET seek from the beginning of the file. The rpos 

argument is the number of bytes from the beginning of 
the file. This value must be positive. 

SEEK—CUR seek from the file’s current position. The rpos 

argument is the number of bytes relative to the current 
position. This value can be positive or negative. 

SEEK END seek from the end of the file. The rpos argument is 

the number of bytes relative to the end of the file. This 
value must be negative or 0. 

Portability ANSI 

Returns A value of — 1 is returned if an error occurs. The external integers 
err no and _OSERR contain additional error information. 

See Also errno, f open, ftell, lseek, _OSERR, rewind 
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f setpos Reposition a file 
Synopsis # include <stdio.h> 


x = fsetpos(fp,pos) ; 

int x; 

FILE *f p ; 

const f pos_t *pos; 

Description The f setpos function positions the file pointed to by the fp argument 
to the position specified by the object pointed to by the pos argument. 
This object is of type f pos_t, which is defined in the stdio . h file. 

The value of the object pointed to by the pos argument should be set 
by a previous call to the f get pos function for the same file. 

The f setpos function can be used with most files, accessed either as 
text or binary. The f setpos function clears the EOF indicator for the 
file on which it is called. 

After a call to the f setpos function on a stream that permits both 
reading and writing, the next file operation may be input or output. 

Portability ANSI 

Returns If successful, the f setpos function returns 0. If it fails, the f setpos 
function returns a nonzero value and stores an appropriate error code in 
the external integer err no. See the description of the external integer 
err no in Chapter 6 for the list of err no values. 

Example See the example for the f get pos function. 


See Also fgetpos, fseek, ftell, lseek 
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fstat Get file status 

Synopsis finclude <sys/stat.h> 

rc = fstat(file, st) ; 

int rc; /* return code */ 

int file; /* UNIX file handle */ 

struct stat *st; /* stat info structure */ 

Description This function obtains information for the given file handle. Permission to 
read, write, or execute the file is not required. 

This function is provided for compatibility with UNIX. It should only 
be called for files opened with the open function. For code that will be 
used only on the Amiga, use the AmigaDOS function Examine instead. 

The information is placed into the stat structure pointed to by the st 
argument. The structure is defined in the file stat .h and contains 
information as follows: 

struct stat { 


unsigned 

short 

st_mode; 

/* 

file mode */ 

ino_t 


st_ino ; 

/* 

inode number */ 

dev_t 


st_dev; 

/* 

file system identifier */ 

char 


*st_rdev; 

/* 

device identifier */ 




/* 

(volume name) */ 

short 


st_nlink; 

/* 

number of links */ 

unsigned short 

st_uid; 

/* 

file owner user-id */ 

unsigned 

short 

st_gid; 

/* 

file group user-id */ 

off t 


st_size; 

/* 

file size in bytes */ 

time_t 


st_atime; 

/* 

time last accessed */ 

time_t 


st_mtime; 

/* 

time last modified */ 

time_t 


st_ctime; 

/* 

time last status change * 

short 


st_type; 

/* 

Amiga file type */ 

char 


*st_comment; 

/* 

Amiga file comment */ 


st is a pointer to a stat structure that must be allocated on a 4-byte 
(long word) boundary by the calling program. A common error is failing 
to allocate the structure before calling the function. You can make sure 
the structure is long-word aligned by either declaring it with the 

aligned keyword or by allocating it dynamically with any SAS/C or 

system allocation function (such as the malloc orAllocMem function). 
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fstat Get file status 
( continued ) 

The following table lists defines that are combined with the logical OR 
operator to form the st_mode field. This list is found in the file 
f nctl . h. 


Symbol 
S — ISCRIPT 
S — IPURE 
S—IARCHIVE 
S—IREAD 

S IWRITE 

S_I EXECUTE 
S—IDELETE 


Meaning 

The object has its script protection bit set. 
The object is an executable. 

The file has its archive bit set. 

The file is readable. 

The file is writable. 

The file is executable. 

The file is deletable. 


Portability UNIX 

Returns If the operation is successful, the function returns 0. Otherwise, it 

returns —1 and places error information in the external integers err no 
and —OSERR. 

See Also chmod, errno, _OSERR 
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ftell 

Synopsis 


Description 


Portability 

Returns 


Get a level 2 file position 
((include <stdio.h> 
apos = ftell(fp); 

long int apos; /* absolute file position */ 

FILE *fp; /* file pointer */ 

The ftell function returns a long integer value that is the current byte 
position in the file, relative to the beginning. It is equivalent to the 
following call: 

apos = lseek(fp->_f ile, OL, 1 ) ; 

It is implemented as a function, not as a macro. 

ANSI 

For the ftell function, an error is indicated by a return value of — 1L. 
The external integers err no and _OSERR contain additional error 
information. 


See Also errno, f open, lseek, _OSERR, tell 
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fwrite Write blocks to a level 2 file 

Synopsis ff include <stdio.h> 

a = fwrite(b,bsize,n,fp) ; 

size_t a; /* actual number of blocks */ 

const void *b; /* pointer to first block */ 
size_t bsize; /* size of block in bytes */ 
size_t n; /* maximum number of blocks */ 

FILE *f p ; /* file pointer */ 


Description This function performs level 2 I/O operations to write blocks of data. 

Each block contains bsize bytes, and up to n blocks are stored into 
contiguous memory locations beginning at location b. 

Blocks are written until n blocks have been sent or until the output 
device cannot accept any more. If the output device becomes full in the 
middle of a block, a partial block is written, but it is not included in the 
function return value. In other words, the return value indicates the 
number of complete blocks that were written. 

Portability ANSI 


Returns This function returns the number of complete blocks that were processed. 
See Also fclose, feof, ferror, fgetc, fopen, fputc, fread, fseek 
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gcvt 

Synopsis 


Description 


Portability 

Returns 

Example 


Convert a floating-point number to a string 
((include <math.h> 


p = gcvt(v,dig, buffer) ; 


char *p; 
double v; 
int dig; 
char *buffer; 


/* points to buffer */ 

/* floating point value */ 

/* number of significant digits */ 
/* output buffer */ 


This function converts the specified floating-point value into a null- 
terminated string in the output buffer. The string will be in one of two 
formats. First, the gcvt function attempts to produce dig significant 
digits in the FORTRAN F format. If that fails, it produces dig significant 
digits in the FORTRAN E format. Trailing zeroes are eliminated, if 
necessary. 

Make sure that the specified buffer is large enough when using this 
function. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

The function returns a pointer to the buffer. 

/* This example displays 314150 */ 

((include <stdio.h> 

((include <stdlib.h> 


void main(void) 

{ 

char s [ 100] ; 

printf("gcvt(3. 141 5e5 , 7 f s ) = ?Ss\n", 
gcvt(3. 1415e5, 7, s) ) ; 


See Also ecvt, fcvt 
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geta4 Establish addressability to the global data area 
Synopsis § include <dos.h> 
void getaH ( void) ; 

Description The geta4 function establishes addressability to the global data area. 

The get a 4 function works as if you compiled your subroutine with the 

saveds option or put the saveds keyword in the declaration. The 

get a 4 function is provided only for compatibility with other compilers. 

The saveds option and saveds keyword are preferred over the 

geta4 function. 


Portability OLD 



276 Chapter 7 


getasn 

Synopsis 


Description 


Portability 

Returns 


Example 


Get assigned device 
jfinclude <dos.h> 
dlist = getasn(name) ; 

struct DeviceList *dlist; /* pointer to device list entry */ 

/* for assignment */ 

const char *name; /* assigned name */ 

Use the getasn function to search the device list for a name. If the 
name is found, the function returns a pointer to the device structure 
defined in the dos/dosextens .h file. You can use the getasn 
function to check whether a logical name is assigned. The getasn 
function can locate logical assigns made with the assign command. It 
can also find volume and device names. 

The following example shows sample syntax for this function: 

if (getasn( "INCLUDE" ) ) open ( "INCLUDE: name" ) 

AmigaDOS 

The value NULL is returned if the value specified in the name argument 
cannot be located in the device list. NULL is defined in the stddef .h 
file. If the name is found, a pointer to the name’s device node is 
returned. Some pointers in the device node are BCPL pointers, and 
strings are BCPL strings. See the file dos/dosextens .h for more 
information. 

Sinclude <stdio.h> 
iinclude <stdlib.h> 

Sinclude <dos.h> 

void main(void) 

{ 

char *type; 

struct DeviceList *volume; 
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getasn Get assigned device 
( continued ) 


volume=getasn( "LC" ) ; /* get LC: device node */ 

if ( volume==NULL) 

( 

fprintf (stderr, "LC: not assigned\n" ) ; 
exit ( EXIT-FAILURE ) ; 

) 

switch ( volume->dl_Type) 

( 

case DLT—DEVICE : 
type = " device"; 
break; 

case DLT— VOLUME : 
type = " volume"; 
break; 
default: 

type = "n assignment"; 
break; 

} 

printf("LC: is a?Ss\n", type); 

) 


See Also getenv, putenv 
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getc 

Synopsis 

Description 

Portability 

Returns 

See Also 


Get a character from a file 
iinclude <stdio.h> 
c = getc( fp) ; 

int c; /* return character or code */ 

FILE *fp; /* file pointer */ 

This function gets a single character from the specified level 2 file. The 
getc function is implemented as a macro to maximize execution speed. 

ANSI 

If successful, the next input character is returned. Otherwise, this 
function returns EOF, which is defined in the file stdio .h. In the event 
of an EOF return, error information can be found in the external integers 
errno and _OSERR. Most programmers treat any EOF return as an 
indication of end-of-file. However, if you want to distinguish errors from 
an end-of-file condition, you should reset the external integer errno 
before calling the function and then analyze its contents when you receive 
an EOF return. 

errno, fgetc, fgetchar, fopen, getchar, _OSERR 
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getcd Get the current directory 
Synopsis # include <dos.h> 


error = getcd(drive,path) ; 


int error; 
int drive; 
char *path 


/* 0 if successful */ 

/* drive code */ 

/* points to path area (255 bytes recommended) */ 


Description This function gets the current directory path for the specified disk drive. 

The drive specification is retained in this implementation for compatibility 
with other implementations. However, you should always set the drive 
argument to 0 because only a value of 0 (indicating the current drive) is 
supported under AmigaDOS. Any other value is considered an error. 

The path area must be large enough to contain the expected path. The 
returned string contains the entire path, including the volume name of 
the device. 


Portability AmigaDOS 

Returns If the operation is successful, the function returns 0. Otherwise, it 

returns —1 and places error information in the external integers err no 
and —OSERR. 


See Also errno, getcwd, _OSERR 
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getch 

Synopsis 

Description 

Portability 

Returns 


See Also 


Get a character from stdin immediately 
((include <stdio.h> 
c = getch (void); 

int c; /* return character or code */ 

This function gets a single unbuffered character from stdin. If the input 
is a console device, it will be put into RAW mode until a character is 
typed, then switched back to the normal buffered mode. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

If successful, the next input character is returned. Otherwise, the 
function returns EOF, which is defined in the file stdio . h. In the event 
of an EOF return, error information can be found in the external integers 
errno and _OSERR. Most programmers treat any EOF return as an 
indication of end-of-file. However, if you want to distinguish errors from 
an end-of-file condition, you should reset the external integer errno 
before calling the function and then analyze its contents when you receive 
an EOF return. 

Note: This function provides the functionality found in the get char 
function in most other compilers on most other platforms. A carriage 
return is not required before the getch function returns a character. 

errno, f getc, fgetchar, f open, getchar, _OSERR 
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getchar 

Synopsis 

Description 

Portability 

Returns 


See Also 


Get a character from stdin 
jfinclude <stdio.h> 
c = getchar ( void) ; 

int c; /* return character or code */ 

This function gets a single character from stdin. 

ANSI 

If successful, the next input character is returned. Otherwise, the 
function returns EOF, which is defined in the file stdio . h. In the event 
of an EOF return, error information can be found in the external integers 
errno and _OSERR. Most programmers treat any EOF return as an 
indication of end-of-file. However, if you want to distinguish errors from 
an end-of-file condition, you should reset the external integer errno 
before calling the function and then analyze its contents when you receive 
an EOF return. 

When reading from an AmigaDOS console device, such as the Shell 
window, the getchar function will not return any characters until the 
user presses the Return key. To see keystrokes as they are typed, either 
use the getch function or put the console device into RAW mode. 

errno, f getc, f getchar, f open, getch, _OSERR 
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getclk Get or change system clock 
Synopsis ((include <dos.h> 

void getclk(clock ) ; 
unsigned char clock[8]; 

Description The getclk function obtains the current setting of the system clock and 
places it into an 8-byte array as follows: 


Byte Contents 

clock [ 0 ] day of the week (0 for Sunday) 

clock [ 1 ] year - 1980 

clock[2] month (1 to 12) 

clock[3] day (1 to 31) 

clock[4] hour (0 to 23) 

clock [ 5 ] minute (0 to 59) 

clock [ 6 ] second (0 to 59) 


clock [ 7 ] hundredths (0 to 99) 


Portability AmigaDOS 
See Also chgclk, errno, _OSERR 
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getcwd 

Synopsis 


Description 


Portability 

Returns 


See Also 


Get the current working directory 
jfinclude <dos.h> 
p = getcwd(b,size) ; 

char *p; /*Same as b if successful, else NULL*/ 

char *b; /*Points to path buffer*/ 

int size; /*Size of path buffer*/ 

This function obtains the path name for the current working directory. If 
the buffer pointer b is not NULL, then the path string is placed there if it 
will fit, and the return pointer p is the same as the pointer b. If the 
pointer b is NULL, then the malloc function is used to obtain a buffer 
of size bytes to hold the path string. In the latter case, you should use 
the free function to release the buffer when you are finished with it. 

The getcd function is often more efficient since it does not use 
memory allocation. 

UNIX 

If the operation is successful, the function returns a pointer to the buffer. 
Otherwise, it returns a null pointer and places error information in the 
external integers errno and _OSERR. Also, a NULL pointer is returned 
if the path string will not fit in the buffer or if a buffer cannot be 
allocated. In either of those cases, the integer errno is unchanged, and 
the integer _OSERR is reset. 

errno, getcd, _OSERR 
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getdfs Get disk free space 

Synopsis | include <dos.h> 

error = getdfs(drive,info) ; 

int error; /*0 if successful*/ 

const char *drive; /*drive or volume name*/ 

/*NULL => current drive*/ 
struct InfoData *info; /*disk information*/ 

Description This function obtains information about the specified disk drive, including 
the amount of free space available. If a NULL pointer is passed as the 
drive name, information is obtained about the current drive. The 
InfoData structure is defined in the file librar ies/dos . h. 

struct InfoData ( 


long 

icLNumSof tErrors ; 

/* 

number of soft errors on disk 

*/ 

long 

id_UnitNumber ; 

/* 

unit on which disk 

is mounted 

*/ 

long 

id_DiskState; 

/* 

see defines in libraries/dos .h*/ 

long 

icLNumBlocks ; 

/* 

number of blocks on 

disk 


long 

id_NumBlocksUsed ; 

/* 

number of blocks in 

use 

*/ 

long 

id_By tesPer Block ; 





long 

id_DiskType; 

/* 

disk type code 


*/ 

BPTR 

ld_VolumeNode; 





long 

id_InUse; 

/* 

flag, 0 if not in use 

*/ 


1 

Portability AmigaDOS 

Returns A return value of 0 indicates success. If the drive code is invalid or no 

disk is mounted on that drive, then the return value is —1. No additional 
information is provided in the external integers err no and _OSERR. 
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getdfS Get disk free space 
(continued) 

Example /* Compute number of bytes available on current drive. */ 

iinclude <stdio.h> 

((include <stdlib.h> 

((include <dos.h> 

void main(void) 

{ 

struct InfoData info; 
long size; 

if (getdfs(0,Sinfo) != 0) 

{ 

printf ( "getdfs failed\n"); 
exit ( EXIT-FAILURE ) ; 

) 

size = (info.id-NumBlocks - info. id_NumBlocksUsed) 

* info. id_ BytesPerBlock; 
printf ( "Current drive has ftd bytes free.\n", 
size) ; 


} 
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getenv 

Synopsis 


Description 


Portability 

Returns 


Get environment variable 
((include <stdlib.h> 
var = getenv ( name ) ; 

char *var; /*environment variable pointer or NULL */ 

const char *name; /*environment variable name */ 

This function searches the environment strings for one that has the 
following form: 

name=var 

The name is the function argument. If such a string exists, the function 
returns a pointer to the var portion, which is null-terminated. Otherwise, 
a NULL pointer is returned. 

Under AmigaDOS, environment variables are obtained by reading the 
file ENV : name, where name is the name you specify. 

The memory returned by the getenv function is obtained with the 
malloc function, so it remains through the duration of your program. If 
you want to return the memory, you can call the free function. 

ANSI 

The value NULL is returned if name cannot be located in the current 
environment. NULL is defined in the stddef .h file. 
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getenv 

( continued ) 

Get environment variable 

Example 

((include <stdio.h> 
((include <stdlib.h> 


char *path; 


void main(void) 


( 

path = getenv ( "PATH") ; /* get PATH variable */ 
if (path == NULL) 


{ 

fprintf (stderr , "No PATH variable\n" ) ; 
exit (EXIT-FAILURE) ; 


) 

printf("PATH environment variable contains :\n" 
"Ss\n", path); 


See Also putenv 
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getfa Get the file attribute 
Synopsis # include <dos.h> 
fa = getfa(name) ; 

int fa; /* 1, -1 f or 0 */ 

const char *name; /* file name */ 

Description This function determines whether or not the specified file is a directory. 

The status is returned in the f a argument and contains the following 
information: 


Status Meaning 

1 directory file 

0 error 

— 1 normal file 


Portability AmigaDOS 


Returns If the operation is unsuccessful, the function returns 0 and places error 
information in the external integers errno and _OSERR. 


See Also errno, _OSERR 
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getfnl Get a filename list 
Synopsis ((include <dos.h> 

n = getfnl(fnp,fna,fnasize,attr) ; 


int n; 

/* 

number of matching file names */ 

const char *fnp; 

/* 

file name pattern */ 

char *fna; 

/* 

file name array */ 

size_t fnasize; 

/* 

size of file name array */ 

int attr; 

/* 

file attribute */ 


Description This function gets all the filenames that match the specified pattern and 
attribute, and it places them into the filename array. Each name is stored 
as a null-terminated string, and the filename array is terminated by a null 
string (a string consisting of only a null byte). If the filename pattern 
includes a path prefix, that prefix is placed in front of each matching 
filename. 

The filename pattern has the following form: 
drive:path/ node, extension 

The function first strips off the drive and directory path portions and 
restricts its search to that area of the file system. The node and extension 
parts can contain any valid filename characters, including the wildcard 
pattern matching characters. AmigaDOS wildcard characters are 

supported by default. Setting the external integer location ms flag to 

a nonzero value causes MS-DOS wildcard characters * and ? to be 
supported instead. Some examples are 

df 0: #? .c 

finds all files on drive dfO: that have . c as their extension. A file 
named abc . c would thus be placed in the array as df 0 : abc . c. This 

assumes that the external integer ms flag is set to 0. 

: abc/def /q* . x? 

finds all files in the directory : abc/def that begin with the letter q 
and have extensions consisting of the letter x and one other letter. For 
example, one such name would be :abc/def/queen.x. This 

assumes that the external integer ms flag is set to 1. 

XYZ* 

finds all files in the current directory that begin with XYZ. One 

example is XYZ. This assumes that the external integer ms flag is 

set to 1. 

AmigaDOS makes no distinction between uppercase and lowercase in 
any part of the filename. 
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getfnl Get a filename list 
( continued ) 

The attribute is an integer defined as follows: 


Attribute Meaning 

0 nondirectory files 

1 all files including directories 


This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability SAS/C 

Returns The function return value is the number of strings stored in the array, 

not including the terminating null string. A value of — 1 is returned if the 
filename pattern is invalid or if there is not enough room in the filename 
array. In the first case, the external integer _OSERR will contain further 
error information. 

Example /* This program constructs an array of pointers to all normal */ 
/* files in the current directory that have an extension */ 

/* of .c. Then the array is sorted into ASCII order. */ 

((include <stdio.h> 

((include <stdlib.h> 

extern long _0SERR; 

void main(void) 

{ 

char names[3000] , *pointers [ 300 ) ; 

int count, i; 

count = getfnl("j(?.c" ( names,sizeof (names) ,0) ; 
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getfnl Get a filename list 
(continued) 

if (count > 0) 

{ 

if (strbpl( pointers, 300, names) != count) 

{ 

fprintf (stderr, "Too many file names\n"); 
exit ( EXIT-FAILURE ) ; 

) 

strsrt(pointers, count) ; 
printf ( "Names Found :\n"); 
for ( i=0 ; iccount; i++) 

( 

printf ( "?Ss\n" , pointers[i ] ) ; 

} 

) 

else 

( 

if (-OSERR) 

( 

poserr( "FILES" ) ; 

) 

else 

{ 

fprintf (stderr, "Too many files\n"); 

) 

exit (EXIT-FAILURE) ; 

} 

) 

See Also dfind, dnext, _OSERR, strbpl, strsrt 
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getft 

Synopsis 


Description 


Portability 

Returns 

See Also 


Get the file time 
iinclude <dos.h> 
ft = getft(name) ; 

long ft; /* file time or -1 if error */ 

const char *name; /* file name */ 

This function gets the time and date information associated with the 
specified file. This information usually indicates when the file was created 
or last updated. This function returns the file time expressed as the 
number of seconds since 00:00:00 Greenwich Mean Time, January 1, 
1970. The function ctime may be used to convert this value into date 
and time in an ASCII string. 

AmigaDOS 

If the getft function is successful, the file time (a long integer) is 
returned. Otherwise, a value of — 1 is returned. Additional error 
information can be found in the external integers errno and _OSERR. 

ctime, errno, _OSERR 
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getmem 

Synopsis 


Description 


Portability 

Returns 

Example 
See Also 


Get a memory block (short) 

((include <stdlib.h> 
p = getmem(sbytes) ; 

void *p; /* block pointer */ 

unsigned int sbytes; /* number of bytes */ 

This function allocates a block from the memory pool and returns a 
pointer to the first byte in the block. If the pool does not currently 
contain a block of sufficient size, the AllocMem function is called to 
obtain more space from the operating system. If that step fails, a NULL 
pointer is returned. 

This function is equivalent to the malloc function. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

OLD 

A NULL pointer is returned if the block could not be allocated. 
Otherwise, a void pointer is returned, but it can be cast to any other 
pointer type. 

See the example for the malloc function, 
malloc, rlsmem, rlsml, slzmem 



294 Chapter 7 


getml 

Synopsis 


Description 


Portability 

Returns 

Example 
See Also 


Get a memory block (long) 

^include <stdlib.h> 
p = getml ( lbytes ) ; 

void *p; /* block pointer */ 

long lbytes; /* number of bytes */ 

This function allocates a block from the memory pool and returns a 
pointer to the first byte in the block. If the pool does not currently 
contain a block of sufficient size, the AllocMem function is called to 
obtain more space from the operating system. If that step fails, a NULL 
pointer is returned. 

This function is equivalent to the ha Hoc function. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

OLD 

A null pointer is returned if the block could not be allocated. 

Otherwise, a character pointer is returned, but it can be cast to any other 
pointer type. 

See the example for the ha lloc function, 
getmem, halloc, rlsmem, rlsml, sizmem 
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getpath 

Synopsis 

Description 

Portability 

Returns 

See Also 


Get the path for a specific directory/file 


((include <dos.h> 

error = getpath ( lock, path); 


int 

error; 

/* 

0 if ok, -1 if error */ 

BPTR 

lock; 

/* 

input */ 

char 

♦path; 

/* 

destination buffer */ 


This function returns the fully specified path string for the directory 
and/or file referenced by the lock. The path argument includes the 
volume name. The destination buffer must be large enough to contain the 
string. 

AmigaDOS 

If the getpath function is successful, it returns 0; otherwise, it returns 
- 1 . 

f indpath, Lock and UnLock ( The AmigaDOS Manual, 3rd Edition ) 
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getreg Get 680x0-specific registers 
Synopsis # include <dos.h> 

x = getreg(reg); /* obtain the current global static base */ 

long x; 
int reg; 

Description The built-in function get reg returns the current contents of a specified 
register. The valid register values (for the reg argument) are defined in 
the file dos . h as follows: 


Register 
Value Name 

Value 

Register 

Name 

Value 

Register 

Name 

0 

REG_D0 

8 

REG_A0 

16 

REG—FPO 

1 

REG—Dl 

9 

REG_A1 

17 

REG-FPl 

2 

REG—D2 

10 

REG—A2 

18 

REG—FP2 

3 

REG—D3 

11 

REG—A3 

19 

REG—FP3 

4 

REG_D4 

12 

REG_A4 

20 

REG—FP4 

5 

REG__D5 

13 

REG_A5 

21 

REG—FP5 

6 

REG—D6 

14 

REG_A6 

22 

REG—FP6 

7 

REG—D7 

15 

REG_A7 

23 

REG-FP7 


The floating-point registers FPO through FP7 are available only on 
Amigas with a math coprocessor. Therefore, you will get an error if you 
attempt to refer to FPO through FP7 when the math=6888 1 compiler 
option is active. 

► Caution Incorrect use of this function can cause serious problems. 

A 

This function is used to read the processor registers directly. For 
example, you can use the get reg function to obtain the value of the 
system registers (for example, A4) to be passed to an interrupt chain. 


Portability SAS/C 
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getreg Get 680x0-specific registers 
( continued ) 

Returns The getreg function returns the current value of the register (a long 
integer). 


See Also emit, putreg 
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gets 

Synopsis 


Description 


Portability 

Returns 

Example 


Get a string from stdin 
jfinclude <stdio.h> 
p = gets(buffer) ; 

char *p ; /*buffer pointer or NULL */ 

char *buffer; /*buffer pointer */ 

The gets function copies characters from the stdin file (the standard 
input file) until a new line or end-of-file is reached. The new line, if 
present, is discarded and the buffer is terminated with a null byte (\0). 

Make sure that your gets buffer can hold the largest line that will be 
encountered while reading the stdin file, because the function does not 
have any way to check for a maximum length. 

ANSI 

This function returns the buffer argument unless an I/O error occurs, in 
which case a NULL pointer is returned, and the external integer err no 
is set to describe the error. 

/* 

* Assume that stdin contains the following lines: 

* Hello, folks! 

* Goodbye, folks! 

*/ 

^include <stdio.h> 

void main(void) 

( 

char *p,b[ 80 ] ; 

/* For the next two lines, p will point to b */ 
p = gets(b); /* b contains "Hello, folks!" */ 
printf("b = ftp, fts\np = ftp\n", b, b, p); 
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gets Get a string from stdin 
(continued) 

p = fgets(b, sizeof(b), stdin); /* b now contains */ 
/* "Goodbye, folks !\n" */ 
printf("b = 95p , Ksp = ftp\n", b, b, p); 

p = gets(b); /* Now, p is NULL */ 
printf("b = %p, flsp = ?5p\n", b, b, p); 


See Also errno, f eof , terror, f getc, f gets, f open, getc 
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gmtime Unpack Greenwich Mean Time (GMT) 

Synopsis # include <time.h> 

ut a gmtime(t); 

struct tm *ut ; 
const time_t *t; 

Description This function unpacks a time value from the long integer form into a 
structure. Normally the time value represents the number of seconds 
since 00:00:00, January 1, 1970, Greenwich Mean Time. (The time 
function returns this type of number.) 

This function expects a pointer as the argument. Do not pass the actual 
time value instead of the pointer. Also, the functions gmtime and 
localtime share a static data area for their return values, and a call to 
either one destroys the results of the previous call. 

The structure tm is defined in the file time . h and has the following 
format: 


struct tm { 

int tm_sec; /* seconds */ 
int tm_min; /* minutes */ 
int tm_hour; /* hours since midnight */ 
int tm_mday; /* day of the month */ 
int tm_mon; /* months since January */ 
int tm_year; /* years since 1900 */ 
int tm_wday; /* days since Sunday */ 
int tm_yday; /* days since January 1 */ 


int tm_isdst; /* daylight savings time flag */ 


Portability ANSI 
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gmtime 

(continued) 

Unpack Greenwich Mean Time (GMT) 

Example 

((include <stdio.h> 
((include ctime. h> 


void main(void) 


( 

struct tm *p; 
long t; 


time( 6t) ; 
p = gmtime ( 6t) ; 

printf("GMT is fts\n" , asctime(p) ) ; 


See Also asctime, ctime, localtime, time 
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halloc 

Synopsis 


Description 


Portability 

Returns 

Example 


Allocate a huge memory block 
({include <stdlib.h> 
p = halloc(n) ; 

void *p; /* pointer to allocated memory */ 

unsigned long n; /* number of bytes to allocate */ 

This function allocates a huge block of memory. In the case of long 
integers, this function is identical to the malloc function. When using 
short integers, it allows allocation of more than 64 megabytes at a time, 
since the parameter is specified as an unsigned long integer. 

Any memory allocated can be freed using the free function, or it will 
be automatically freed when the program terminates. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The pointer is NULL if the request cannot be fulfilled. 

/* 

* Get space for 30,000 records, 30 bytes each 
*/ 

((include <stdio.h> 

((include <stdlib.h> 

void main(void) 

{ 

char *p; 

p = halloc(90000L) ; 
if (p == NULL) 

( 

printf ( "cannot allocate record space\n"); 
exit ( EXIT-FAILURE ) ; 

) 

free(p) ; 

) 

free, amalloc, sbrk 


See Also 
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labs Integer absolute value 
Synopsis ft include <stdlib.h> 
ai = iabs ( i ) ; 
int ai,i; 


Description This function computes the absolute value of integers or short integers. 

This function is not available if the _STRICT__ANSI flag has been 
defined. 


Portability SAS/C 

Returns This function returns an integer holding the absolute value of the 
parameter. 

See Also abs 
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iomode 

Synopsis 

Description 

Portability 

Returns 

See Also 


Change the mode of a level 1 file 

({include <fcntl.h> 

error = iomode ( fh, mode ) ; 

int error; /* error code */ 

int fh; /* file handle */ 

int mode; /* 0 => translated mode */ 

/* 1 => raw mode */ 

This function changes the mode of the specified level 1 file. When in 
translated mode, carriage returns are deleted on input, and a carriage 
return is inserted before each line feed on output. In RAW mode, all data 
in the file are transferred as is. 

The iomode function affects only the software translation that is done 
by the level 1 I/O service functions. 

SAS/C 

A nonzero return value indicates that the specified file handle is not 
associated with a level 1 file. 

open 
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is..... Test character types 
Synopsis j| include <ctype.h> 


t 

= 

isalnum(c) ; /* 

Test 

if 

alphanumeric character 

*/ 

t 

= 

isalpha(c) 

/* 

Test 

if 

alphabetic character 

*/ 

t 

= 

isascii(c) 

/* 

Test 

if 

ASCII character 

*/ 

t 

= 

iscntrl(c) 

/* 

Test 

if 

control character 

*/ 

t 

= 

iscsym(c) ; 

/* 

Test 

if 

C symbol character 

*/ 

t 

= 

iscsymf (c) 

/* 

Test 

if 

C symbol lead character 

*/ 

t 

= 

isdigit (c) 

/* 

Test 

if 

decimal digit character (0 to 9 

) */ 

t 

= 

isgraph(c) 

/* 

Test 

if 

graphic character 

*/ 

t 

= 

islower(c) 

/* 

Test 

if 

lower case character 

*/ 

t 

= 

isprint(c) 

/* 

Test 

if 

printable character 

*/ 

t 

= 

ispunct(c) 

/* 

Test 

if 

punctuation character 

*/ 

t 

= 

isspace( c) 

/* 

Test 

if 

space character 

*/ 

t 

= 

isupper(c) 

/* 

Test 

if 

upper case character 

*/ 

t 

= 

isxdigit(c); /* 

Test 

if 

hex digit character 

*/ 




/* 

(0 

to 9, A to F, a to f) 

*/ 


int t; /* 0 if false, non-zero if true */ 
int c: /* character to test */ 

Description These functions test for various character types. If you include the file 

ctype . h, the functions are defined as macros. If you do not include the 
file ctype . h, these functions are resolved in the library. If you want to 
use the function versions (not the macros) but must include the file 
ctype.h for some other reason, use an tfundef statement to undefine 
the appropriate character test macros. 

You can use either characters or integers as arguments, but the macros 
are defined only over the integer range from —1 to 255. The functions, 
however, will return a result for values above 255, but the results are 
not necessarily correct and cannot be relied upon. The reason — 1 is 
included as a valid argument is to avoid a nonsensical result if you feed 
the EOF value to one of the macros or functions. EOF can be returned by 
the get char function and other I/O functions, and if you pass it to any 
of the character test functions, the return value will be 0. 

When you include the ctype.h file, these functions generate inline 

code to test the static array named ctype. This array contains a bit 

mask for each of the 256 possible character values and for the integer 
value —1. If you do not include the ctype.h file, you reduce your 
program size slightly at the expense of execution speed. 

The is ascii, iscsym, and iscsyraf functions are not available if 
the strict ANSI flag has been defined. 
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is 

(continued) 

Portability 

Returns 

Example 


Test character types 


SAS/C isascii, iscsym, iscsymf 
ANSI all others 

These functions return a nonzero value if the test is true and 0 if the test 
is false. 


((include <stdio.h> 
((include <ctype.h> 

void main(void) 

( 

int c; 


while((c = getchar()) != EOF) 

{ 

printf ( "\n55c Xs alphabetic. \n" , 

c, isalpha(c) ? "is" : "is 


) 

} 


not" ) ; 


See Also ctype 
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isatty Test a file descriptor for a terminal device 
Synopsis § include <fcntl.h> 
rc = isatty(fd) 


int f d ; /* level 1 file descriptor */ 

int rc; /* return code */ 


Description This function takes a file descriptor as returned from a call to the 

level 1 file I/O function open and tests to see if the file descriptor is 
associated with a terminal device (such as a console window). 

Portability UNIX 

Returns If the file descriptor is associated with a terminal device, the routine 
returns 1. Otherwise, it returns 0. 


See Also open 
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jrand48 

Synopsis 

Description 

Portability 

Returns 

See Also 


Generate a random long integer (external seed) 
finclude <raath.h> 
z = jrand48 ( seed) ; 

long z; /* random long */ 

unsigned short seed [ 3 1 ; /* seed value (high bits in seed[0]) */ 

This function generates random numbers using the linear congruential 
algorithm and 48-bit arithmetic. The j rand 4 8 function is provided for 
cases where several seeds are in use at the same time, so you can specify 
the seed on each function call. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

The j rand 4 8 function returns signed long integers uniformly distributed 
over the interval from —2**31 to 2**31 — 1. 

lcong48, rarand, rand, srand, srand48 
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labs 

Synopsis 

Description 

Portability 

Returns 


Long integer absolute value 
((include <stdlib.h> 
al = labs ( 1 ) ; 
long int al,l; 

This macro computes the absolute value of a long integer. It generates 
inline code to perform the conversion. The definition is 

({define labs(i) ( ( i ) <0?— ( i ) : (i) ) 

ANSI 

This function returns a long integer holding the absolute value of the 
parameter. 


See Also abs, fabs, iabs 
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lcong48 

Synopsis 


Description 


Portability 


Set linear congruence parameters 
jfinclude <math.h> 
void lcong48 (parm) ; 

unsigned short parra[7]; /* parameters */ 

The lcong48 function allows an intricate initialization of the linear 
congruential algorithm. The algorithm is of the form: 

X x+1 = (a * X n + c) mod m 

The value of m is 2**48, and the default values for a and c are 
0x5DEECE66D and OxB, respectively. The array passed to the lcong48 
function is structured as follows: 


Parameter Value 


parm[ 0 ] 

bits 47-32 of value X„ 

parm[ 1 ] 

bits 31-16 of value X n 

parm[ 2 ] 

bits 15-00 of value X n 

parm[ 3 ] 

bits 47-32 of value a 

parm[ 4 ] 

bits 31-16 of value a 

parm[ 5 ] 

bits 15-00 of value a 

parm[ 6 ] 

value c 


Whenever the seed 4 8 function is called, the a and c arguments are 
reset to their default values. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 


See Also jrand48, rand, seed48, srand, srand48 
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Idexp 

Synopsis 


Description 


Portability 

Returns 


Combine floating-point value 
((include <math.h> 


v = ldexp(d,x); 


double v; 

/* 

value */ 


double d; 

/* 

fraction 

*/ 

int x; 

/* 

exponent 

*/ 


The Idexp function adds the integer x to the exponent in the argument 
d, which is the same as computing: 

v = d * (2 ** x) 

If d and x are the results of the f rexp function, then the Idexp 
function performs the reverse of the frexp function. Also, if the 
absolute value of the resulting exponent is greater than 1,023, then the 

mat her r function is called with an overflow or underflow error 

indication. 

ANSI 

This function returns a double-precision floating-point number holding 
the result of the above equation. 


See Also fmod, frexp, matherr, modf 
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Idiv 

Synopsis 

Description 

Portability 

Returns 

Example 


Return the long integer quotient and the remainder 

((include <stdlib.h> 

res = ldiv(numer, denom); 

ldiv_t res; /* resulting quotient and remainder */ 

long int numer; /* numerator for the divide */ 

long int denom; /* denominator for the divide */ 

This function returns the quotient and the remainder obtained from 
performing a divide on long integers. 

ANSI 

This function returns a structure containing both the quotient and the 
remainder. The structure is defined in the stdlib.h file as follows: 

typedef struct { 
long int quot; 
long int rem; 

} ldiv_t; 

/* 

* Obtain both quotient and remainder 

* for a value divided by 10 
*/ 

((include <stdio.h> 

((include <stdlib.h> 

void quotrem(long val) 

{ 

ldiv_t result; 

result = ldiv(val, 10L); 

printf ( "Quotient = Sld\n", result. quot) ; 
printf ( "Remainder = iSld\n", result. rem); 

} 
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Idiv Return the long integer quotient and the remainder 
( continued ) 


void main(void) 

I 

quotrem(42) ; 

} 


See Also di 
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localeconv Return information on locale formatting conventions 
Synopsis ((include <locale.h> 

lcl = localeconv( void) ; 

struct lconv *lcl; /* Locale information structure */ 

Description This function fills in a structure of information about numeric and 

monetary formatting for the current program’s locale. The structure is 
defined in the file locale. h as follows: 

struct lconv ( 

char *decimal_point ; 
char *thousands_sep; 
char *grouping; 


((define LCONVM int_curr_symbol 

char *int_curr_symbol; /* international currency symbol */ 

/* for current locale */ 

char *currency_symbol ; /* local currency symbol for */ 

/* current locale */ 

char *mon_decimal_point; /* decimal point for monetary */ 

/* quantities */ 

char *mon_thousands_sep; /* separator for groups of digits */ 

/* in monetary quantities */ 

char *mon_grouping; /* size of digit groups in */ 

/* monetary quantities */ 

char *positive_sign; /* string indicating non- */ 

/* negative monetary quantity */ 

char *negative_sign; /* string indicating negative */ 

/* monetary quantity */ 

char int_frac_digits; /* number of digits after decimal */ 

/* point in international */ 

/* monetary quantities */ 

char frac_digits; /* number of digits after decimal */ 

/* point in monetary quantities */ 

char p_cs_precedes ; /* 1=currency symbol precedes */ 

/* nonnegative monetary quantity */ 

/* 0=symbol succeeds quantity */ 
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localeconv Return information on locale formatting conventions 
(continued) 


char 

p_sep_by_space; 

/* 

1=space between currency symbol*/ 



/* 

and non-negative monetary 

*/ 



/* 

quantity 

*/ 



/* 

0=no space 

*/ 

char 

n_cs_precedes ; 

/* 

1=currency symbol precedes 

*/ 



/* 

negative monetary quantity 

*/ 



/* 

0=symbol succeeds quantity 

*/ 

char 

n_sep_by_space; 

/* 

1=space between currency symbol*/ 



/* 

and negative monetary quantity 

*/ 



/* 

0=no space 

*/ 

char 

p_sign_posn; 

/* 

position of sign for positive 

*/ 



/* 

monetary quantities 

*/ 

char 

n_sign_posn; 

/* 

position of sign for negative 

*/ 



/* 

monetary quantities 

*/ 


); 

The decimal point character used to format nonmonetary values defaults 
to a period (.)• The character used to separate groups of digits before the 
decimal point character in formatted nonmonetary values defaults to a 
comma (,). 

Portability ANSI 

Returns This function returns a pointer to the lconv structure for the current 
locale. 


See Also 


setlocale 
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localtime 

Synopsis 


Description 


Portability 

Example 


Unpack local time 

((include <time.h> 

ut = localtime(t) ; 

struct tm *ut; 
const time_t *t; 

This function unpacks a time value from the long integer form into a 
structure. Normally, the time value represents the number of seconds 
since 00:00:00, January 1, 1970, Greenwich Mean Time. (The time 
function returns this kind of number.) The local time function adjusts 
the number for the local time zone. 

This function expects a pointer as the argument. A common error is to 
pass the actual time value instead of the pointer. Also, the functions 
gmtime and local time share a static data area for their return values, 
and a call to either one destroys the results of the previous call. 

The structure tm is defined in the file time . h. See the description of 
the gmtime function for the format of the tm structure. 

ANSI 

((include <stdio.h> 

((include <time.h> 

void raain(void) 

( 

struct tm *p; 
long t; 

time ( St) ; 

p = localtime( fit) ; 

printf ( "Local time is 55s\n" , asctime(p) ) ; 

) 


See Also a sctime, ctime, gmtime, time 
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log 

Synopsis 

Description 

Portability 

Returns 


Natural logarithm function 
ifinclude <math.h> 
r = log(x); 
double r, x; 

The log function calculates the base E logarithm. This function requires 

a positive argument. If you enter a negative argument, the matherr 

function is called with a DOMAIN error. 

ANSI 

This function returns a double-precision floating-point number that 
contains the base E logarithm of the parameter. 


See Also logio, matherr 
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loglO Base 10 logarithm function 
Synopsis # include <math.h> 
r = log 1 0 ( x ) ; 
double r, x; 


Description The log 10 function calculates the base 10 logarithm. This function 
requires a positive argument. If you enter a negative argument, the 
raatherr function is called with a DOMAIN error. 


Portability ANSI 

Returns This function returns a double-precision floating-point number that is 
base 10 logarithm of the parameter. 

See Also log, matherr 
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longjmp 

Synopsis 


Description 


Portability 
See Also 


Perform a long jump 

((include <setjrap.h> 

void longjmp(save, value) ; 

jmp_buf save; /* address of save area */ 
int value; /* return value */ 

The set jmp function saves the current stack mark in a specified save 
area and returns a code of 0. A subsequent call to the longjmp function 
with the same save area will then cause control to return to the next 
statement after the original set jmp call, with value as the return code. 
If the return code is 0, it is forced to 1 by the longjmp function. 

This mechanism is useful for quickly popping back up through multiple 
layers of function calls under exceptional circumstances. 

Do not call the longjmp function with an invalid save area. It may 
disrupt the system. Do not use the longjmp function after the function 
calling the set jmp function has returned to its caller because the stack 
frame for that function no longer exists. 

From within a shared library, you must not call any library functions 
that terminate your program. For example, you cannot call exit, 

exit, or abort from a shared library. You also cannot use set jmp 

and longjmp to jump across a call from the program into the library. 

ANSI 

exit, set jmp 
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Iqsort 

Synopsis 


Description 

Portability 
See Also 


Sort an array of long integers 
((include <stdlib.h> 
void lqsort(la,n) ; 

long *la; /* pointer to long int array */ 
size_t n; /* number of elements in array */ 

The Iqsort function sorts the specified array of long integers using the 
ACM 271 algorithm, more popularly known as Quicksort. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

dqsort, fqsort, qsort, sqsort, tqsort 
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Irand48 

Synopsis 

Description 

Portability 

Returns 

See Also 


Generate a random positive long integer (internal seed) 

((include <math.h> 
y = lrand48 ( void) ; 

long y; /* random positive long */ 

This function generates random numbers using the linear congruential 
algorithm and 48-bit arithmetic. The 1 rand 4 8 function uses an internal 
48-bit storage area for the seed value. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

The 1 rand 4 8 function returns nonnegative long integers uniformly 
distributed over the interval from —2**31 to 2**31 — 1. 

nrand, rand, srand, srand48 
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Isbrk 

Synopsis 

Description 

Portability 

Returns 

See Also 


Allocate memory 

(linclude <stdlib.h> 

p = lsbrk(lbytes) ; 

void *p; /* block pointer */ 

long lbytes; /* number of bytes */ 

The Isbrk function requests lbytes of memory from the system, 
adding the allocated block to a linked list of memory blocks to be 
returned to the system when the program terminates. 

This function is provided for compatibility with previous versions of 
the compiler. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

OLD 

An error is indicated by a NULL pointer. The Isbrk function returns the 
address of the block just allocated. 

getmem, malloc, rbrk, sbrk 
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Iseek Set a level 1 file position 
Synopsis # include <fcntl.h> 

apos = lseek(fh,rpos,mode) ; 


long apos; 
int fh; 
long rpos; 
int mode; 


/* absolute file position */ 
/* file handle */ 

/* relative file position */ 
/* seek mode */ 


Description This function moves the byte cursor of a level 1 file to a new position. 
The mode argument must be one of the following: 

0 seek from the beginning of the file. The rpos argument is the 
number of bytes from the beginning of the file. This value must be 
positive. 

1 seek from the current position of the file. The rpos argument is the 
number of bytes relative to the current position. This value can be 
positive or negative. 

2 seek from the end of the file. The rpos argument is the number of 
bytes relative to the end of the file. This value must be negative or 0. 

If the Iseek function is asked to move 0 bytes relative to the current 
position, it simply returns the current file position. 

Returns This function returns — 1 if an error occurs, in which case the external 
integers err no and _OSERR contain additional error information. 

Portability UNIX 


Example /** 

* This program totals the number of bytes used by 

* all normal files in the current directory. 

**/ 


((include <stdio.h> 

((include <stdlib.h> 

((include <fcntl.h> /* for Level 1 I/O */ 


char names [8192]; 


/* holds file names */ 
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Iseek Set a level 1 file position 
( continued ) 


void main(void) 

{ 

char *p; 
int f,n; 
long x,y; 

if (getfnl( "#?" ,names , sizeof (names) ,0) <= 0) 

( 

printf( "Can't build file name list\n"); 
exit ( EXIT-FAILURE ) ; 

} 

for (x=0, n=0, p=names; *p!='\0'; p+=strlen(p)+1 ) 

{ 

f = open(p,0_ RDONLY) ; 
if (f < 0) 

{ 

printf( "Can't open \"J5s\"\n" ,p) ; 
exit ( EXIT-FAILURE ) ; 

) 

y = lseek( f , 0L, 2 ) ; 
if (y < 0) 

{ 

printf("Seek failure on \"fts\"\n" ,p ) ; 
exit ( EXIT-FAILURE ) ; 

} 

x += y; 
n++; 

close( f ) ; 

) 

printf("Xd files, % Id bytes used\n" ,n,x) ; 


See Also errno, open, _OSERR, tell 
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Istat Get file status 

Synopsis # include <sys/stat.h> 

rc = lstat(file, s t ) ; 

int rc; /* return code */ 

const char *file; /* file name */ 

struct stat *st; /* stat info structure */ 

Description This function obtains information for the given file. If the file is not in 
the current directory, the file path must be included as part of the 
filename. Permission to read, write, or execute the file is not required. 

If the file referred to is a link, this function returns information on the 
link instead of the file to which it is linked. 

This function works under all revisions of the operating system and is 
provided for compatibility with UNIX. For code that will be used only on 
the Amiga, use the AmigaDOS function Examine instead. 

The information is placed into the stat structure pointed to by the st 
argument. The structure is defined in the file stat .h and contains 
information as follows: 

struct stat { 


unsigned 

short 

st_mode; 

/* 

file mode */ 

ino_t 


st_ino; 

/* 

inode number */ 

dev_t 


st_dev; 

/* 

file system identifier */ 

char 


*st_rdev; 

/* 

/* 

device identifier */ 
(volume name) */ 

short 


st_nlink; 

/* 

number of links */ 

unsigned 

short 

st_uid; 

/* 

file owner user-id */ 

unsigned 

short 

st_gid; 

/* 

file group user-id */ 

off t 


st_size; 

/* 

file size in bytes */ 

time_t 


st_atime ; 

/* 

time last accessed */ 

time_t 


st_mtime ; 

/* 

time last modified */ 

time_t 


st_ctime ; 

/* 

time last status change */ 

short 


st_type; 

/* 

Amiga file type */ 

char 


*st_comment ; 

/* 

Amiga file comment */ 


); 


st is a pointer to a stat structure that must be allocated on a 4-byte 
(long word) boundary by the calling program. A common error is failing 
to allocate the structure before calling the function. You can make sure 
the structure is long-word aligned by either declaring it with the 
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Istat Get file status 
( continued ) 


aligned keyword or by allocating it dynamically with any SAS/C or 

system allocation function (such as the malloc or AllocMem function). 

The following table lists defines that are combined with the logical OR 
operator to form the st_mode field. This list is found in the file 
f nctl . h. 


Symbol 

S ISCRIPT 

S — IPURE 

S IARCHIVE 

S—IREAD 
S—IWRITE 
S_I EXECUTE 
S—IDELETE 


Meaning 

The object has its script protection bit set. 
The object is an executable. 

The file has its archive bit set. 

The file is readable. 

The file is writable. 

The file is executable. 

The file is deletable. 


Portability UNIX 

Returns If the operation is successful, the function returns 0. Otherwise, it 

returns —1 and places error information in the external integers err no 
and _OS ERR. 


See Also chmod, errno, _ OSERR 
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main 

Synopsis 

Description 


Portability 
See Also 


Standard preprocessing for the main module 

((include <stdlib.h> 

void stdargs main(line); 

char *line; /* ptr to command line that caused execution */ 

The ma i n function performs the standard preprocessing for the main 

module of a C program. It accepts a command line of the following form: 

program-name a rgl arg2 

It builds a list of pointers to each argument and the first pointer is to 

the program name. The main function also opens the standard I/O 

files stdin, stdout, and stderr. main calls the function main 

with the standard argc and argv parameters. 

Unlike previous editions of the compiler, this function is declared with 
the stdargs keyword. 

The source code for this function is in the file _main . c in the 
sc:source directory. 

For more information on main, refer to Chapter 10, “Using Startup 

Modules, Autoinitialization, and Autotermination Functions,” in SAS/C 
Development System User’s Guide, Volume 1: Introduction, Editor, 
Compiler. 

SAS/C 

main 
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main Your main or principal function 
Synopsis § include <workbench/startup.h> 
int main(argc,argv) ; 

int argc; /* argument count */ 

char *argv[ ] ; 

Description This function does not actually exist in the library; you must supply one 
of these main programs in each of your applications. If you trace through 
the two startup modules c . a and _main . c, you will find that the 
module c . a passes control to the module _main . c, which then calls the 
function named main. Since the source code for both of these modules is 
supplied, you are free to change this initialization procedure for special 
applications. The standard version simulates UNIX’s interface with C 
programs by setting up a vector, which is simply an array of pointers. 

The argv array contains pointers to the command-line arguments, and 
the argument argc indicates how many pointers are in the array. For 
example, you can start the program my prog with the following 
command: 

myprog abc def "ghi jkl" 

Then, the startup code sets up the argv array as follows: 


argv[0] 

=> 

"myprog" 

argv[1] 

=> 

"abc" 

argv[2] 

=> 

"def" 

argv[3] 

=> 

"ghi jkl" 

argv[4] 

=> 

NULL 


The argc argument contains the value 4. 

Under Workbench, there is no command line. In this case, the 
argument argc is 0 indicating no command or arguments, and the 
argument argv is actually a pointer to the Workbench startup message 
structure. You can convert it with a simple cast: 

jfinclude <workbench/startup.h> 

struct WBStartup *Wbs; 


Wbs = (struct WBStartup *)argv; 
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main Your main or principal function 
( continued ) 


Portability ANSI 

Returns When the main function returns to its caller (normally the _main . c 

function), the program exits to AmigaDOS with a termination code of the 
value returned by main. If you want to pass a nonzero termination code 

back to AmigaDOS, use the exit or exit function, or return a 

nonzero return code from your main function. 

Example /* This program is intended to run only under the */ 

/* Shell and displays the command and any arguments */ 

Sinclude <stdio.h> 

int main(int argc, char *argv[J) 

( 

int i; 

printf ( "command = %s\n" ,argv[ 0 ] ) ; 
for (i = 0; argc > 0; i++, argc—) 

printf ( "argument $d = JSs\n" ,i,argv[i] ) ; 
return( 0) ; 

} 

/* This program is intended to run only under WorkBench and */ 
/* gets its arguments from the WorkBench message structure */ 

Sinclude <stdlib.h> 

Sinclude <stdio.h> 

Sinclude <workbench/startup.h> 

int main(int argc, char *argv[]) 

( 

struct WBStartup *wbs; 
int i; 

if (argc != 0) 

exit (EXIT-FAILURE) ; 


wbs = (struct WBStartup *)argv; 
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main Your main or principal function 
(continued) 

printf ( "command = fts\n", wbs->sm_ArgList[0] .wa_Name) ; 
for (i = 1; i < wbs->sra_NumArgs ; i++) 
printf ( "argument 55d = %s\n" , 

i, wbs->sm_ArgList(iJ .wa_Name) ; 

return(O) ; 

) 

/* This program runs correctly under either Workbench or */ 

/* the Shell and can be used with stack or registerized */ 

/* parameters. */ 

^include <stdio.h> 

finclude <workbench/startup.h> 

int main (int argc, char *argv[]) 

( 

struct WBStartup *msg; 

int i; s* 

if (argc != 0) 

( 

printf ( "command = 5Ss\n", argv[0]); 
for (i=0; argc > 0; i++, argc — ) 

printf ( "argument %d = fts\n", i, argv [ i 1 ) ; 

} 

else 

{ 

msg = (struct WBStartup *)argv; 

printf ( "command = ?Ss\n", msg->sm_ArgList [ 0 ] . wa_Uame) ; 
for (i=1; i < msg->sm_NumArgs ; i++) 

printf ( "argument 55d = 55s\n", i, msg->sm_ArgList [ i ] .wa_Name) ; 

} 

return ( 0) ; 


See Also exit, exit, main 
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malloc Allocate memory 
Synopsis #include <stdlib.h> 
b = malloc(n) ; 

void *b ; /*block pointer */ 
size_t n; /*number of bytes */ 

Description The malloc function allocates a block that is n bytes long and is aligned 
in such a way that you can cast the block pointer to any pointer type. If 
the block cannot be allocated, a NULL pointer is returned. 

The malloc function can only allocate 64 kilobytes at a time if short 
integers are used. 

Portability ANSI 

Returns A null pointer is returned if there is not enough space for the requested 
block. 

Example ((include <stdio.h> 

((include <stdlib.h> 

((include <string.h> 

struct LIST 

{ 

struct LIST *next; 
char text [2] ; 

I; 


void main(int argc, char *argv[]) 

I 

struct LIST *p ; 
struct LIST *q ; 
struct LIST list; 
char b[ 256 ] ; 
int x; 

printf ("\nBegin new group. . ,\n") ; 
for (q = Slist; ; q = p) 

{ 

printf ( "Enter a text string: "); 
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malloc Allocate memory 
(continued) 

if (fgets(b, sizeof (b) ,stdin) == NULL) 

( 

break; 

) 

if (b[ 0 ] == NULL) 

( 

if (q == Slist ) 

{ 

printf ( "\n" ) ; 
exit ( EXIT-SUCCESS ) ; 

} 

break; 

) 

x = sizeof ( struct LIST) - 2 + strlen(b) + 1; 
p = malloc(x) ; 
if (p == NULL) 

{ 

printf ("No more memory\n"); 
exit (EXIT-FAILURE) ; 

) 

q->next = p; 
p->next = NULL; 
strcpy(p->text, b); 

) 

printf ("\n\nTEXT LIST...\n"); 
p = list. next; 
while (p ! = NULL) 

{ 

q = p->next; 

printf ( "55s" , p->text); 

free(p) ; 

P = q; 

} 

list. next = NULL; 


See Also calloc, free, getmem, rbrk, realloc, rlsraem, sbrk 
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_matherr 

Synopsis 


Description 


Portability 

Returns 


Math error handler 
((include <math.h> 
a = — matherr (x) ; 

int a; /* action code */ 

struct — exception *x; /* exception vector */ 

The matherr function is called whenever one of the higher-level 

math functions detects an error. The exception vector structure is defined 
in the file math.h and contains information about the error as follows: 

struct exception 

{ 


int type; 

/* 

error type 

*/ 

char *name; 

/* 

math function name 

*/ 

double argl , arg2; 

/* 

function arguments 

*/ 

double retval; 

/* 

proposed return value 

*/ 


}; 

The codes for the type field in struct exception are in the 

file math . h. 

The standard library version of the matherr function translates 

the error type into a UNIX error code that is placed into the external 
integer err no. Then the function returns an action code of 0 to indicate 
that the math function should simply use the proposed return value. In 
other words, the math function will pass that value back to its caller. 

The SAS/C Compiler software includes source code in the source 

directory for the matherr function, so you can change it to do more 

sophisticated error correction. One typical change is to place a different 
return value into the exception vector and then return a nonzero action 
code. This informs the math function that the return value has been 
changed. You must compile the modified matherr . c file and link the 
resultant object module with your code to incorporate the changes. 

UNIX 

For the matherr function, a nonzero return indicates that the 

proposed return value in the exception vector has been changed and that 
the new value should be used. A return of 0 indicates that the proposed 
return value is acceptable. 
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matherr Math error handler 

(continued) 


See Also except, _fperr 
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max Compute the maximum of two values 
Synopsis (f include <math.h> 
v = max(a,b) ; 

Description This macro computes the maximum of two arithmetic values. It is defined 
as follows: 

((define max(a,b) ( (a)>(b)?(a) : (b) ) 

The max macro works with any arithmetic type or combination of types. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


Portability UNIX 

Returns This macro returns the larger of the two parameters. 
See Also min 
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mblen 

Synopsis 


Description 

Portability 

Returns 


See Also 


Determine the length of a multibyte character 
ifinclude <stdlib.h> 
length = mblen(s, n) ; 

int length; /* length or state information */ 

const char *s; /* pointer to characters or NULL */ 

size_t n; /* maximum number of characters to look at */ 

This function determines the number of bytes comprising the multibyte 
character pointed to by the argument s, and it is useful for determining 
how much storage to allocate before calling the mbs t owes function. 

ANSI 

If a NULL pointer is passed for the argument s, the return value 
indicates whether the current locale has state-dependent encodings. A 
nonzero value indicates that it does. 

In the Amiga implementation, for all other values for the argument s, 
a 1 is returned since the implementation does not support multibyte 
characters. 

mbstowes, mbtowc 
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mbstowcs 

Synopsis 


Description 

Portability 

Returns 


Convert a multibyte string to a wide character string 

((include <stdlib.h> 

length = mbstowcs ( pwcs , s, n); 

size_t length; /* length or state information */ 

wchar_t *pwcs; /* pointer to wide character string */ 

const char *s; /* pointer to characters or NULL */ 

size_t n; /* maximum number of characters to look at */ 

This function converts a multibyte string to a wide character string. 

The mbstowcs function for the current locale is passed the input 
parameters and the result is returned. 

ANSI 

This function returns the length of the result string. 


See Also mblen, mbtowc 
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mbtowc Map a multibyte character to a wide character 
Synopsis # include <stdlib.h> 

length = mbtowc (pwc, s, n); 


int length; 

/* 

length or state information 

*/ 

wchar_t *pwc; 

/* 

pointer to wide character 

*/ 

const char *s; 

/* 

pointer to characters or NULL 

*/ 

size_t n; 

/* 

maximum number of characters to 

look at */ 


Description This function maps a multibyte character to a wide character. The output 
buffer must be long enough to hold the result. You can determine the 
length by calling the mblen function. 

Portability ANSI 

Returns This function returns the length of the multibyte character defined by the 
locale information. If the argument s is null or if the argument n is 
equal to 0, this function returns 0. 


See Also mblen, mbtowc 
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memccpy 

Synopsis 


Description 


Portability 

Returns 

See Also 


Copy a memory block 

((include <string.h> 

s = memccpy ( to, from,c,n) ; 

void *s ; /* return pointer */ 

void *to; /* destination pointer */ 

const void *from; /* source pointer */ 
int c ; /* character value */ 

unsigned n; /* number of bytes */ 

This function, which was introduced with UNIX System V, copies blocks 
of memory. 

Copying stops once either of these conditions is true: 

□ the specified block size has been copied 

□ the specified character has been copied. 

The memccpy function does not handle overlapping memory blocks. If 
you specify overlapping blocks to this function, the results are 
unpredictable. 

This function neither recognizes nor produces the NULL terminator 
byte usually found at the end of strings. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The memccpy function returns a pointer to the character after the 
argument c in the from block, or a NULL pointer if the c argument was 
not found in the first n characters. 

memcpy, strcpy 
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memchr 

Synopsis 


Description 

Portability 

Returns 


Find a character in a memory block 
linclude <string.h> 
s = memchr (a ,c,n ) ; 

void *s; /* pointer to character in block */ 

const void *a; /* block pointers */ 

int c; /* character value */ 

size_t n; /* number of bytes */ 

This function finds the first occurence of a character in a block of 
memory. 

This function does not terminate at a NULL byte. It always searches n 
bytes. 

ANSI 

The memchr function returns a pointer to the first occurrence of the 
specified character in the block, or a NULL pointer if the character is not 
found. 
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MemCleanup 

Synopsis 

Description 


Deallocate all allocated memory 

((include <stdlib.h> 

void stdargs _MemCleanup( void) ; 

The —MemCleanup function traverses the linked list of allocated memory 
to release any memory allocated using SAS/C library functions and not 
yet returned to the system. No cleanup is performed for memory 
allocated with Amiga operating system calls. 

This function is normally called from the SAS/C startup code as a 
program is terminating. You can replace the standard —MemCleanup 
function with one of your own. 


Portability AmigaDOS 
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memcmp 

Synopsis 


Description 


Portability 

Returns 


Compare two memory blocks 
finclude <string.h> 
x = memcmp ( a , b , n ) ; 

int x; /* return value */ 

const void *a,*b; /* block pointers */ 

size_t n; /* number of bytes */ 

This function compares two blocks of memory, character by character. 

The memcmp function has a built-in version that is equivalent to the 
standard library versions. A built-in version generates inline 68000 
instructions without needing to make calls to the library. The statement 
# include <str ing . h> provides a default setting by which any 
built-in functions are accessed. If you do not want the built-in function, 
you can use an #undef memcmp statement after including the 
string . h file. 

This function does not terminate at a NULL byte. It always searches n 
bytes. 

ANSI 

The memcmp function returns an integral value as follows: 


Return Meaning 

negative first block sorts below the second 

zero first block equals the second 

first block sorts above the second 


positive 
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memcpy 

Synopsis 

Description 


Portability 

Returns 

See Also 


Copy a memory block 

Hinclude <string.h> 

s = memcpy ( to, from,n) ; 

void *s; /* return pointer */ 

void *to; /* destination pointer */ 

const void *from; /* source pointer */ 
size_t n; /* number of bytes */ 

This function, which was introduced with UNIX System V, copies blocks 
of memory. 

The memcpy and movmem functions are similar, except the former was 
introduced with UNIX V, while the latter is a traditional SAS/C function. 
The memcpy function does not handle overlapping memory blocks. If you 
specify overlapping blocks to this function, the results are unpredictable. 
You may want to use the ANSI function memmove instead, since it does 
handle overlapping blocks. 

The memcpy function has a built-in version that is equivalent to the 
standard library versions. A built-in version generates inline 68000 
instructions without needing to make calls to the library. The statement 
#include <string.h> provides a default setting by which any 
built-in functions are accessed. If you do not want the built-in function, 
you can use an #undef memcpy statement after including the 
string . h file. 

The memcpy function does not place a NULL byte at the end of the 
block, but it always copies n bytes. 

ANSI 

The memcpy function returns a pointer to the start of the destination 
block. 

memccpy, memmove, movmem, strcpy 
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memmove 

Synopsis 


Description 

Portability 

Returns 

Example 


Copy bytes in memory 
finclude <string.h> 


p = memmove (dest, from, nbytes); 


void *p; 
void *dest; 
const void *from; 
size_t nbytes; 


/* same as dest 
/* destination for 
/* source of bytes 
/* number of bytes 


*/ 

moved bytes */ 
for move */ 
to be transferred */ 


This function copies the specified number of bytes from one memory 
location to another. It checks the relative addresses supplied to determine 
the direction of transfer that will avoid overlap. 

ANSI 

The memmove function returns a pointer to the destination block. 

/* 

* Make room to insert a word in a character string. 

* 

* This program produces the following output: 

* This is a test 

* This is not a test 
*/ 

{(include <stdio.h> 

{{include <string.h> 

void main(void) 

{ 

char string! 100] ; 

strcpy( string, "This is a test"); 
print f ( "8s\n" , string) ; 


/* Shift the words "a test" to make room */ 
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memmove 

(continued) 


Copy bytes in memory 


/* WARNING: Make sure you have plenty of space in */ 
/* the area you are working with. memmove() and */ 
/* others do NOT stop at the terminating NULL of */ 
/* a string, so will blithely write over any */ 

/* memory you tell them to. This can lead to */ 
/* different types of problems, from simple */ 

/* "strange occurrences" to spectacular crashes! */ 

memmove (string+1 1 ,string+7,strlen(string+7)+1 ) ; 
memcpy( string+7 , " not ",5); 
printf("Js\n", string) ; 


See Also memcpy, movmem, strcpy 
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memset Set a memory block to a value 


Synopsis # include <string.h> 


s = memset ( to, c,n) ; 


void *s ; 
void *to ; 
int c; 
size_t n; 


/* return pointer */ 

/* destination pointer */ 
/* character value */ 

/* number of bytes */ 


Description This function which is compatible with UNIX, sets a block of memory to 
a value. 

The memset function has a built-in version that is equivalent to the 
standard library versions. A built-in version generates inline 68000 
instructions without needing to make calls to the library. The statement 
# include <str ing . h> provides a default setting by which any 
built-in functions are accessed. If you do not want the built-in function, 
you can use an #undef memset statement after including the 
string . h file. 

This function neither recognizes nor produces the NULL terminator 
byte usually found at the end of strings. 


Portability ANSI 


Returns The memset function returns a pointer to the destination block. 
See Also setmem 
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min 

Synopsis 

Description 


Portability 
Returns 
See Also 


Compute the minimum of two values 
jfinclude <math.h> 
v = min(a,b) ; 

This macro computes the minimum of two arithmetic values. It is defined 
as follows: 

((define min(a,b) { (a)<=(b)?(a) : (b) ) 

This macro works with any arithmetic type or combination of types. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

This macro returns the smallest of the two parameters, 
max 
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mkdir 

Synopsis 


Description 

Portability 

Returns 


Make a new directory 
((include <dos.h> 
error = mkdir(path) ; 

int error; /* 0 if successful */ 

const char *path; /* points to new directory path string */ 

This function makes a new directory in the specified path. For example, if 
the path is sys:/abc/def/ghi, then the new directory is named ghi 
and is in the path /abc/def on the volume labeled sys : . For 
AmigaDOS, the path may begin with a drive or volume name and a 
colon. 

UNIX 

If the operation is successful, the function returns 0. Otherwise, it 
returns —1 and places error information in the external integers err no 
and _OS ERR. 


See Also errno, _ OSERR, rmdir 
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mkstemp 

Synopsis 

Description 


► Caution 

Portability 

Returns 

Example 


Make a unique filename and open the file 
Hinclude <unistd.h> 
fh = mkstemp! char *template); 
int fh; /* file handle */ 

The mkstemp function replaces the contents of the string pointed to by 
template with a unique filename, opens that file for reading and 
writing, and returns a file handle for the file, mkstemp prevents any 
conflict between testing whether the file exists and opening the file for 
use (race conditions). 

The string in template is a filename with embedded X letters, mkstemp 
replaces the Xs with a letter or a digit from the current process address, 
beginning with the low-order digits. If the template does not contain 
enough Xs to accomodate all of the digits in the address, the high-order 
digits are dropped first. The letter is dropped last. 

You can enter as many Xs in the template as you want. 

Do not use this function with constant strings. This function modifies 
the content of the buffer sent to it, so any constants are changed. If 
you compile with the strmerge option, you could modify your code 
section. 

UNIX 

If successful, this function returns a file handle, which is an integer equal 
to or greater than 0. If the file could not be created, mkstemp returns 
- 1 . 

^include <stdio.h> 

[(include <stdlib.h> 
linclude <string.h> 

[(include <unistd.h> 

int raain(void) 

( 

char buffer [32] ; 
int fd; 
int rc; 

strcpy( buffer, "Tempi at eXXXXXXXX" ) ; 
fd = mkstemp(buf fer) ; 
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mkstemp 

(continued) 


Make a unique filename and open the file 


if (fd == -1) ^ 

( 

printf ( "mkstemp ( ) failed!\n"); 
rc = EXIT-FAILURE; 

} 

else 

{ 

printf ("File \"%s\" created. You should delete it!\n", buffer); 

close( fd) ; 

rc = EXIT-SUCCESS; 

) 

return rc; 


See Also mktemp, open, tmpf ile, tmpnam 
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mktemp Make a unique filename 
Synopsis § include <unistd.h> 

ptr = mktemp (char *template); 

char *ptr; /* pointer to the template */ 


Description The mktemp function replaces the contents of the string pointed to by 
template with a unique filename and returns the address of template. 

The string in template is a filename with embedded X letters, mktemp 
replaces the Xs with a letter or a digit from the current process address, 
beginning with the low-order digits. If the template does not contain 
enough Xs to accomodate all of the digits in the address, the high-order 
digits are dropped first. The letter is dropped last. 

You can enter as many Xs in the template as you want. 

► Caution Do not use this function with constant strings. This function modifies 
the content of the buffer sent to it, so any constants are changed. If 
you compile with the strmerge option, you could modify your code 
section. 


Portability UNIX 

Returns This function returns a pointer to the template. If the first character in 
the template is NULL, then mktemp failed to create a unique filename. 
Otherwise, the name in the template is a unique filename. 

Example jf include <stdio.h> 

((include <stdlib.h> 

((include <string.h> 

((include <unistd.h> 


int main(void) 

( 

char buffer! 32 ] ; 
int rc; 

strcpy (buffer, "TemplateXXXXXXXX" ) ; 
mktemp (buffer) ; 
if (buffer[0] == 0) 

{ 

printf ( "mktemp ( ) failed! \n"); 
rc = EXIT-FAILURE; 
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mktemp Make a unique filename 
(continued) 

) 

else 

{ 

prlntf ( "mktemp ( ) created \"Xs\"\n", buffer); 
rc = EXIT-SUCCESS ; 

) 

return rc; 

) 

See Also mkstemp, tmpfile, tmpnam 
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mktime 

Synopsis 

Description 

Portability 

Returns 

Example 


Convert the broken-down time to a time_t value 
((include <time.h> 
t = mktime (ts) ; 

time_t t; /* number of seconds since 1/1/70 */ 

struct tm *ts; /* broken down time structure */ 

This function converts the broken-down time, expressed as local time, to 
a time_t value identical to what the time function would return for 
the specified date and time. 

ANSI 

The mktime function returns the number of seconds since January 1, 
1970. 

/* 

* 

* Get a time value for a very important event 

* Sept 8, 1988 20:16:02 

* 

*/ 

((include <stdio.h> 

((include <time.h> 

void main(void) 

( 

struct tm inputtm; 
time_t event; 


inputtm. tm_sec = 02; 

/* 

seconds after the minute 

*/ 

inputtm. tm_min = 16; 

/* 

minutes after the hour 

*/ 

inputtm. tm_hour = 20; 

/* 

hours since midnight 

*/ 

inputtm. tm_mday = 8; 

/* 

day of the month 

*/ 

inputtm. tm_mon = 9; 

/* 

months since January 

*/ 

inputtm. tm_year = 88; 

/* 

years since 1900 

*/ 

inputtm. tm_isdst = 1; 

/* 

Daylight Savings Time flag 

*/ 
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mktime Convert the broken-down time to a time_t value 
( continued ) 

event = mktime ( 6 inputtm) ; 


printf("JSd seconds passed between 1/1/70, 00:00:00" 
" and 9/8/88, 20:16:02\n", event); 


See Also time 
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modf Split a floating-point value 
Synopsis ((include <math.h> 
x = modf (y,p) ; 

double x; /* fractional part of y */ 
double y; /* number to be broken up */ 
double *p; /* integral part of y */ 

Description The modf function separates the integral and fractional parts of the 
argument y and returns them as two double-precision floating-point 
numbers. Both parts have the same sign as the y argument. The 
fractional part is the number that would be obtained by calling the fmod 
functions as follows: 


x = fmod(y, 1.0); 


Make sure that the second argument of the modf function is a pointer 
to a double-precision floating-point number. Do not use a pointer to an 
integer. 

Portability ANSI 

Returns The function return value is the fractional part of the argument y, and 
the integral part is placed in the double-precision floating-point number 
pointed to by the argument p. 

Example ^include <stdio.h> 

((include <math.h> 

void modit(double fi) 

I 

double ff; 


ff = modf ( 1 .2, Sfi) ; /* ff contains 

printf ("modf ( 1.2, J51f) = 5Slf\n", fi, ff); 


*/ 


void main(void) 

( 


modit( 1.0); 
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modf Split a floating-point value 
( continued ) 


See Also fmod 
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movmem 

Synopsis 


Description 

Portability 
See Also 


Move a memory block 

((include <string.h> 

void movmem(from,to,n) ; 

const void *frora; /* source pointer */ 
void *to; /* destination pointer */ 

unsigned n; /* number of bytes */ 

This function moves blocks of memory. The movmem function handles 
overlapping memory blocks correctly. 

This function does not terminate on a NULL byte. It always moves 
exactly n bytes. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

memmove 
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mrand48 Generate a random long integer (internal seed) 

Synopsis # include <math.h> 
z = mrand48 ( void) ; 
long z; /* random long */ 

Description This function generates random numbers using the linear congruential 
algorithm and 48-bit arithmetic. The mrand48 function uses an internal 
48-bit storage area for the seed value. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability UNIX 

Returns The mrand48 function returns signed long integers uniformly distributed 
over the interval from —2**31 to 2**31 — 1. 

See Also jrand48, lcong48, nrand48, rand, srand 
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nrand48 Generate a random positive long integer (external seed) 

Synopsis # include <math.h> 
y = nrand48(seed) ; 

long y; /* random positive long */ 

unsigned short seed[3]; /* seed value (high bits in seed [ 0 ] ) */ 


Description This function generates random numbers using the linear congruential 
algorithm and 48-bit arithmetic. The nr and 4 8 function is provided for 
cases where several seeds are in use at the same time, so you can specify 
the seed on each function call. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


Portability UNIX 

Returns The nr and 4 8 function returns nonnegative long integers uniformly 
distributed over the interval from 0 to 2**31 — 1. 

See Also jrand48, lcong48, lrand48, mrand48, rand, srand 
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Off Setof Get the byte offset of a structure member 
Synopsis i include <stddef.h> 

size_t of f setof (type, element); 


Description The offsetof macro returns a size_t constant specifying the decimal 
byte offset of a component within a structure. This constant is generated 
at compile time. Padding for alignment, if any, is included. The operands 
of the offsetof function are a structure type (type) and structure 
member (element). The element does not include the structure type 
or the selection operators . or ->. 

Portability ANSI 

Returns The offsetof function returns the byte offset of element, within the 
structure type. 

Example This section contains several examples of the use of the offsetof 

macro. In these examples, the member specification is written as it would 
be written to access the value of a structure member, except that there is 
no leading . or -> selection operator. 


((include <stddef.h> 

struct AAA {/* Define structure AAA */ 
double ddd; 
char ccc; 
int bbb; 

}; 


size_t 


x ; 


/* x is the byte offset of component bbb in */ 
/* struct AAA */ 
x = of f setof ( struct AAA, bbb); 
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offsetof Get the byte offset of a structure member 
(continued) 


The following example shows a structure, data, with an inner structure 
base. 

finclude <stddef.h> 

struct data ( /* Define struct data */ 
int id; 
int *elem; 
char *name; 

struct ( /* Define struct type base */ 

double proj; 

) base; 


long ofs; 

/* ofs is the byte offset of base. proj */ 
ofs = of fsetof ( struct data, base. proj); 

In the following example, complex is defined with a typedef 
statement to be a structure type. The component specification 
inner . d [ 5 ] specifies an array element within an inner structure. The 
variable y is set to the offset of the sixth array element in the inner 
structure (decimal 5 6). 

((include <stddef.h> 

typedef struct { /* Define struct type complex */ 

struct XXX *xptr, *xptr2; 
struct {/* Define struct type inner */ 
int count, count2; 
double d [ 10] ; 

} inner; 

struct XXX *xptr3; 

) complex; 

/* y is the byte offset of inner. d [ 5 ] */ 
long y; 

y = offsetof (complex, inner.d(5]); 
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onbreak 

Synopsis 


Description 


Portability 

Returns 


Plant a break trap 

^include <dos.h> 

error = onbreak( func) ; 

int error; /* 0 if successful */ 

int (*func) ( void) ; /* pointer to function to be called */ 

This function plants a break trap, which is simply a function that gets 
called whenever the user enters Control-C or Control-D. The standard 
break keys Control-E and Control-F are ignored by the onbreak 
function. 

The onbreak function can perform any AmigaDOS operations. If it 
returns a value of 0, then execution resumes at the interrupted point. 
Otherwise, the program is aborted immediately. 

If the func argument is NULL, then the current break trap, if any, is 
removed and the default interrupt handler is restored. With the default 
handler, Control-C and Control-D cause a requester to appear on the 
screen with choices to continue or abort. 

Detection of Control-C and Control-D is performed during level 1 I/O. 
Explicit checks for these events can be forced by calls to the function 
chkabort. 

AmigaDOS 

The onbreak function returns 0 if it was successful. The break trap 
function should return 0 to continue execution and a nonzero value to 
abort. 
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Onbreak Plant a break trap 
( continued ) 

Example This program tests the onbreak function. After the initial message is 

printed, you should get the Break received message when you press 
Control-C or Control-D. The second time causes the program to terminate. 

Iinclude <stdio.h> 

Iinclude <dos.h> 

int 1=0; 

int brk(void) /* This is the break function */ 

( 

printf ( "Break received. . . \n" ) ; 
return( i++) ; 

} 

void raain(void) /* This is the main program */ 

( 

printf ( "Setting break trap...\n"); 
if (onbreak(Sbrk) ) 

( 

printf ( "Can't set break trap\n"); 

} 

while( 1 ) 

{ 

chkabort(); /* check for CTRL-C */ 

) 


See Also chkabort, signal 
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onexit 

Synopsis 


Description 


► Caution 

Portability 

Returns 

Example 


Set an exit trap 
{{include <stdlib.h> 
success = onexit( func) ; 

int success; /* non-zero for success */ 

void (*func) ( void) ; /* trap function pointer */ 

This function establishes an exit trap (function) that is called when the 
program terminates. The trap function is called just before the program 
returns to the operating system. All buffers are flushed and files are 
closed before the trap is called. User-allocated memory is not yet freed. 

This implementation of the onexit function allows only one trap. 
Each call to the onexit function overrides the previous trap. If you call 
the onexit function with a NULL pointer, the current trap is removed. 
(You can use the at ex it function instead, at ex it allows more than 
one trap and is an ANSI standard function.) 

The exit trap is called after all files have been closed. 

Do not call the print f or cprintf function from within the exit trap. 

▲ 

OLD 

If the function is successful, a nonzero value is returned. 

/* This program tests the onexit function. */ 

{{include <stdlib.h> 

({include <stdio.h> 

int ex(i) /* This is the exit trap function */ 
int i; 

( 

WRITE(Output( ) , "Exit trap hit\n",14); 
return( 0 ) ; 
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onexit Set an exit trap 
( continued ) 


void main(void) 


/* This tests the exit trap */ 


printf ( "Setting exit trap...\n"); 
if ( !onexit(ex) ) 

printf ("Can't set trap...\n"); 
printf ( "Exiting with code 2\n"); 
exit(2) ; 

} 


See Also atexit, exit 
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Open Open a level 1 file 
Synopsis ((include <fcntl.h> 


fh = open (name, mode , prot ) ; 


int fh; 

const char *name; 
int mode; 
int prot; 


/* file handle */ 
/* file name */ 

/* access mode */ 
/* protection mode 


(O-CREAT only) */ 


Description This function opens a file so that it can be accessed with the level 1 I/O 
functions. The filename can be any character string that is a valid 
filename, and it may include a device code and a directory path. The 
access mode is formed by combining the appropriate symbols using the 
logical OR operator ( | ) from the following list of conventional UNIX 
symbols: 

0_ RDONLY specifies read-only access. No writes are allowed. 
O—WRONLY specifies write-only access. No reads are allowed. 

0 RDWR specifies read-write access. Both reads and writes are 

allowed. 


0 NDELAY 

O—APPEND 

O-TRUNC 

O-CREAT 

O-EXCL 


is defined for UNIX compatibility and has no effect under 
AmigaDOS. 

is normally used in conjunction with the O—WRONLY or 
0— RDWR symbols. It causes the I/O system to seek to the 
end of the file before the first write operation, 
specifies that if the file exists, it is truncated to a length of 
0. This flag is normally used with the 0_ CREAT, 

O—WRONLY or 0— RDWR symbol. 

specifies that if the file does not already exist, it is created. 
The protection mode argument is provided for compatibility 
with existing software, but is ignored under AmigaDOS. To 
set the protection use the chmod function to change the 
protection bits after the file has been closed, 
is used only with the 0_ CREAT symbol. If the 0_ EXCL and 
0— CREAT symbols are both present and the file already 
exists, the open function will fail. 


The prot parameter is only required if the mode is equal to 0_ CREAT. 
The protection bits are defined in the file dos/dos.h. 
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Open Open a level 1 file 
( continued ) 

Portability UNIX 

Returns If the operation is successful, the function returns a file handle, which is 
an integer equal to or greater than 0. Otherwise, it returns — 1 and 
places error information in the external integers errno and _OSERR. 

See Also chmod, close, creat, errno, _OSERR 
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opendir 

Synopsis 


Description 

Portability 

Returns 


Initiate a directory operation 
ifinclude <sys/dir.h> 
dfd = opendir(dirname) ; 

DIR *dfd; /* return directory file descriptor */ 

const char *dirname; /* directory name */ 

Given a directory name, this routine opens the directory for read access. 
UNIX 

If successful, this function returns a pointer to a handle that contains the 
following information: 


typedef struct _dirdesc 


long dd_fd; 
long dd_loc; 
long dd_size; 
char *dd_buf; 
DIR; 


/* system directory lock */ 
/* current directory posn */ 
/* size of dcLbuf in bytes */ 
/* system structure info */ 


If it is not successful, this function returns NULL pointer. 

Example /* An example of opening and searching the contents */ 
/* of a directory for a particular entry. */ 

((include <sys/dir.h> 

((include <stdio.h> 

((include <stdlib.h> 

((include <string.h> 

int searchdir(char *dname f char *file) 

{ 

int rc; 

DIR *dfd; /* directory descriptor */ 

struct dirent *dptr; /* dir entry */ 

rc = 0 ; 

dfd = opendir (dname) ; 
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Opendir Initiate a directory operation 
( continued ) 

while ((dptr = readdir(dfd) ) != NULL) 

( 

if ( !stricmp(file, dptr->d_name ) ) 

{ 

rc = 1 ; /* Found a match */ 
break; 

} 

) 

closedir(dfd) ; 
return (rc) ; 


void main(int argc, char *argv[J) 

( 

if (argc < 3) 

( 

printf( "Usage: OpenDir <dirname> <f ilename>\n" ) ; 
exit ( EXIT-FAILURE ) ; 

) 

if (searchdir(argv( 1 ) , argv[2]) == 0) 

( 

printf("File \"Ss\" not found in " 

"directory \"Xs\"!\n", 
argv[2], argv ( 1 ] ) ; 
exit (EXIT-FAILURE) ; 

) 

printf ( "Found it ! \n" ) ; 


See Also closedir, readdir, seekdir, telldir 
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OVlyMgr Overlay manager call point 

Synopsis MOVEQ #ovent,D0 
JMP ovlyMgr 


Description This function is the main entry point to the overlay manager that is called 
whenever control is to be transferred to an alternate overlay node. The 
input parameter is an index into the overlay ordinate table that is 
constructed by the linker. These offsets are automatically assigned by the 
linker, and all calls to routines across overlay node boundaries are 
automatically routed through the overlay manager entry point. 

Source code for the overlay manager is found in the ovs . a file in the 
source directory. 

Calls through the overlay manager destroy registers DO, Dl, AO, and 
Al. Therefore, registerized parameters do not work, and all calls through 
the overlay manager should use standard stack-based parameter passing 
( stdargs). 

Portability AmigaDOS 
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perror 

Synopsis 

Description 


Portability 
See Also 


Print error message 
((include <stdio.h> 
void perror(s) ; 

const char *s; /* message prefix */ 

This function checks the external integer err no and, if it is nonzero, 
sends an error message to stderr. The message consists of the specified 
prefix, a colon, a space, and the message text from the external array 

named sys_errlist. This array contains pointers to the various 

UNIX error messages. The highest error number is given by the contents 

of the external integer sys_nerr. The SAS/C Compiler software 

contains the source for these two external items in a file named syserr 

that allows you to modify the messages. The sys_nerr external 

integer and the sys_errlist external array are declared in the 

header file errno . h. 

ANSI 

errno, poserr, sys_errlist, sys_nerr 
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poserr 

Synopsis 


Description 


Portability 

Returns 

See Also 


Print AmigaDOS error message 
{(include <dos.h> 
error = poserr(s) ; 

int error; /* contents of _0SERR */ 

const char *s; /* message prefix */ 

This function checks the external integer _OSERR and, if it is nonzero, 
sends an error message to stderr. The message consists of the specified 
prefix, a colon and space, and the message text from the external array 

named os_errlist. This array of structures contains pointers to the 

various AmigaDOS error messages. The highest error number is given by 

the contents of the external integer os_nerr. The os_errlist 

external array and the os_nerr external integer are declared in the 

file err no . h. The SAS/C Compiler software contains the source for 
these two external items in a file named os err . c, which you can modify 
to customize or expand the messages. 

AmigaDOS 

The function returns the contents of the external integer _OSERR so you 
can test for an error condition and print a message in one step, as in the 
example: 

if (poserr ( "foo" ) ) goto abort; 

_OSERR, perror 
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printf 

Synopsis 


Description 


Portability 

Returns 

Example 


Formatted print to stdout 

((include <stdio.h> 

length = printf (fmt.argl ,arg2, ...) ; 

int length; /* number of characters generated */ 

const char *fmt; /* format string */ 

.... argx; /* arguments */ 

This function produces an output stream of ASCII characters and sends 
the output to stdout. stdout is usually the user’s screen (console). 

The printf function has a built-in version that is equivalent to the 
standard library version. The effect of a call to the printf function is 
that the most efficient internal version of the printf function is used. 

This function works like the f printf function. See the description of 
the f printf function earlier in this chapter for a complete description. 

ANSI 

This function returns the number of output characters generated. 

/* 

* This example prints a message indicating whether 

* the function argument is positive or negative. 

* In the second printf, the width and precision 

* are 15 and 8, respectively. 

*/ 

((include <stdio.h> 

void pneg(double value) 

( 

char *sign; 

if (value < 0) 

( 

sign = "negative"; 

) 

else 

{ 

sign = "not negative"; 

) 


printf ("The number &E is fts.\n" f value f sign) ; 



374 Chapter 7 


printf Formatted print to stdout 
(continued) 

printf ("The number JS*.*E is Xs.\n " , 15,8,value,sign) 

} 

void main(void) 

( 

pneg(37.8) ; 
pneg (—18.2) ; 

) 


See Also fprintf 
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pow 

Synopsis 

Description 

Portability 


Raise a number to a power 
({include <math.h> 
r = pow(x,y) ; 
double r, x, y; 

The pow function raises the argument x to the y power. If x is negative 

and y is not an integral value, the matherr function is called with a 

DOMAIN error. 

ANSI 


See Also matherr, pow2 



376 Chapter 7 


pow2 

Synopsis 

Description 

Portability 

Returns 


Raise 2 to a power 
I include <math.h> 
r = pow2( x) ; 
double r, x; 

The pow2 function computes 2**x by calling the pow function. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The return value r is the value 2**x. 


See Also 


matherr 
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PROLOG Profiler -PROLOG hook 
Synopsis jf include <sprof.h> 

void asm -PROLOG (register aO const char *where); 

void asm _EPIL0G( register aO const char *where); 

Description If you compile a function with the profile option, —PROLOG and 

—EPILOG are automatically called when the function is entered or exited, 
respectively. —PROLOG and —EPILOG were designed for use by the 
sprof utility, but you can replace them with your own code and use 
them for any purpose. The SAS/C versions of —PROLOG and —EPILOG 
note the time the function was entered and exited and pass this 
information to the sprof utility, which produces a report telling you 
how much time was spent in each function. 

If you declare —PROLOG and —EPILOG in your code, make sure you 

declare them with the asm and register aO keywords as 

shown. If you declare either —PROLOG or —EPILOG, you must declare 
both, even if one of them simply returns immediately, 
sc: source/ profile. c contains the source code for the SAS/C 
versions of —PROLOG and —EPILOG and the autoinitialization and 
autotermination functions associated with them. 

The parameter where is passed on the stack. It points to a character 
string of the following form: 

" \module\function\line" 
where 

module is the name of the file containing the function 
function is the name of the function 

line is the line number on which the function begins. 

For example, if you have a function f oo beginning on line 17 of the file 
f oo . c, the where parameter would be 

"\foo.c\foo\17" 

A null where parameter indicates that the PROFILER— ON or 
PROFILER— OFF macro has been called. PROFILE— OFF turns off 
profiling for the code that follows it. PROFILE_ON reinstates profiling. 
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_PROLOG Profiler —PROLOG hook 
(continued) 

For more information about profiling, —PROLOG, —EPILOG, 

PROFILE— ON, and PROFILE—OFF, refer to the description of the sprof 
utility in SAS/C Development System User’s Guide, Volume 2. 


Portability SAS/C 
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putc 

Synopsis 


Description 

Portability 

Returns 

See Also 


Put a character to a level 2 file 

((include <stdio.h> 

r = putc(c,fp) ; 

int r; /* EOF or c */ 

int c; /* Character to be output */ 

FILE *fp; /* Level 2 file pointer */ 

This function puts a single character to the specified level 2 file. The 
putc function is implemented as a macro to maximize execution speed. 
Therefore, you should not pass expressions that may have side effects to 
the putc function. For example, putc ( C++ , fp) may increment c more 
than once. 

ANSI 

If successful, this function returns the character to be output; otherwise, 
it returns EOF. For disk files, an EOF return usually means that the disk 
is full. However, this type of return can also occur if the device is write- 
protected or if a write error occurs. In any case, additional error 
information can be found in the external integers errno and _OSERR. 

errno, fopen, _OSERR 
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putchar 

Synopsis 


Description 

Portability 

Returns 


See Also 


Put a character to stdout 

((include <'3tdio.h> 

r = putchar (c) ; 

int r; /* EOF or c */ 

int c; /* Character to be output */ 

This function puts a single character to the level 2 file stdout. The 
putchar function is implemented as a macro to maximize execution 
speed. Therefore, you should not pass expressions that may have side 
effects to the putchar function. For example, putchar (C++) may 
increment c more than once. 

ANSI 

If successful, this function returns the character that was output; 
otherwise, it returns EOF. For disk files, an EOF return usually means 
that the disk is full. However, this type of return can also occur if the 
device is write-protected or if a write error occurs. In either case, 
additional error information can be found in the external integers err no 
and _OSERR. 

errno, fopen, _OSERR 
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putenv Put a string into the environment 
Synopsis ((include <stdlib.h> 
error = putenv (env); 

int error; /* 0 if successful */ 

const char *env; /* environment string */ 


Description The putenv function accepts a string and places it into the current 
environment. This string has the form: 

name=var 

If the environment already contains a string beginning with the specific 
name then that string is replaced; otherwise, the new string is added. The 
text of var is written into the file env : name. 

Environment variables on the Amiga are global so that writing an 
environment variable from one process sets the variable for all processes. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability UNIX 

Returns If the putenv function is unable to write to the file env : name, it 
returns a nonzero return code. 


Example ((include <stdio.h> 
((include <stdlib.h> 


void main(void) 

( 

char *e; 


if (putenv( "HOCUS=pocus" ) ) /* Add HOCUS */ 

( 

printf ( "Couldn ' t add HOCUSVn"); 
exit ( EXIT-FAILURE ) ; 

} 

printf ( "Environment variable HOCUS added\n" ); 
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putenv Put a string into the environment 
( continued ) 


e = getenv( "HOCUS" ) ; /* Read HOCUS */ 

if (e == NULL) 

{ 

printf ( "Couldn't read H0CUS\n"); 
exit ( EXIT-FAILURE ) ; 

} 

printf ( "Environment variable HOCUS contains: Ss\n" f e 

printf ( "Removing environment variable HOCUS\n"); 
if ( putenv ( "H0CUS= " ) ) /* Remove HOCUS */ 

{ 

printf ( "Couldn't remove HOCUSNn"); 
exit (EXIT-FAILURE) ; 

) 

printf ( "Done. \n" ) ; 


See Also getenv 
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putreg Set up 680x0-specific registers 

Synopsis § include <dos.h> 

void putreg(reg,x) ; 

int reg; /* register number */ 
long x; /* value of reg */ 

Description The built-in function putreg assigns a value to a register. The valid 

register values (for the reg argument) are defined in the file dos . h as 
follows: 


Value 

Register 

Name 

Value 

Register 

Name 

Value 

Register 

Name 

0 

REG_D0 

8 

REG— AO 

16 

REG—FPO 

1 

REG_D1 

9 

REG— A1 

17 

REG-FPl 

2 

REG— D2 

10 

REG_A2 

18 

REG— FP2 

3 

REG—D3 

11 

REG—A3 

19 

REG-FP3 

4 

REG_D4 

12 

REG— A4 

20 

REG-FP4 

5 

REG—D5 

13 

REG_A5 

21 

REG—FP5 

6 

REG—D6 

14 

REG_A6 

22 

REG—FP6 

7 

REG— D7 

15 

REG—A7 

23 

REG-FP7 


The floating-point registers FPO through FP7 are available only on 
Amigas with a math coprocessor. Therefore, you will get an error if you 
attempt to refer to FPO through FP7 when the math=6888 1 compiler 
option is active. 

► Caution Incorrect use of this function can cause serious problems. ▲ 

Portability SAS/C 

Example putreg (REG_A4,x) ; /* set up the current global static base */ 


See Also getreg 
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puts 

Synopsis 


Description 

Portability 

Returns 

Example 


Put string to stdout 
((include <stdio.h> 
error = puts(s); 

int error; /*non-zero if error*/ 

const char *s; /*string pointer*/ 

The puts function copies string s to stdout (the standard output file). 
The terminating NULL byte is not copied, but a new line character (\n) is 
sent after the string. 

ANSI 

If an error occurs, the return value is —1; otherwise, it is 0. Additional 
error information can be found in the external integers err no and 

-OSERR. 

/* 

* This examples writes the following two lines to stdout: 

* 

* This is the first line 

* This is the second line 
*/ 

((include <stdio.h> 

void main(void) 

( 

puts ("This is the first line"); 
fputs("This is ", stdout); 
puts ("the second line"); 

1 


See Also 


errno, ferror, fopen, fputc, fputs 
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qsort Sort a data array 
Synopsis # include <stdlib.h> 

void qsort (a, n, size, cmp) ; 

void *a; /* data array pointer */ 

size_t n; /* number of elements in array */ 

size_t size; /* element size in bytes */ 

/* pointer to comparison function */ 
int (*cmp) (const void *, const void *); 

Description The qsort function sorts the specified array using the ACM 271 

algorithm, more popularly known as Quicksort. During its operation, it 
calls upon the specified comparison routine with pointers to the two array 
elements being compared. The comparison routine should return an 
integral result as follows: 


Return Meaning 

negative first element is below the second 

positive first element is above the second 

zero elements are equal 


Portability ANSI 
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raise 

Synopsis 

Description 

Portability 

Returns 

Example 


Generate a signal 
((include <signal.h> 
ret = raise(sig) ; 

int ret; /* 0 if successful, nonzero if failed */ 

int sig; /* signal to generate */ 

This function simulates the generation of a signal and invokes the proper 
signal handler for that signal. 

ANSI 

A nonzero return value indicates failure. 

/* 

* Cause a floating point overflow 
*/ 

((include <signal.h> 

void main(void) 

( 

raise(SIGFPE) ; 


See Also 


matherr, onbreak, signal 
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rand Generate a random number 
Synopsis ((include <stdlib.h> 
x = rand( void) ; 

int x; /* random number */ 

Description The rand function returns pseudo-random numbers in the range from 0 
to the maximum positive integer value (RAND—MAX). 

See the dr and 4 8 function and its related functions for more 
sophisticated random number generation. 

Portability ANSI 

Returns This function returns an integer value as noted above. 

Example /* 

* This example prints 1000 random numbers 
*/ 

((include <stdio.h> 

((include <stdlib.h> 

((include <string.h> 

void main(int argc, char *argv[]) 

{ 

int i, x; 

if (argc > 1) 

{ 

stcd_i(argv[ 1 ] ,Sx) ; 
if (x == 0) 

{ 

x = 1; 

) 

) 

else 

( 

x=time(NULL); 

) 

srand(x) ; 

printf("Seed value is Xd\n",x); 
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rand Generate a random number 
( continued ) 


printf("Here are 1000 random numbers ... \n" ) ; 
for(i = 0; i < 200; i++) 

( 

printf("555d S5d £5d %5d 555d\n" f 

rand( ) ,rand( ) ,rand( ) ,rand( ) ,rand( ) ) ; 

) 

printf ( "\n\n" ) ; 


See Also drand48, srand 
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rawcon 

Synopsis 


Description 


Portability 

Returns 

Example 


Set or unset raw console input 

((include <stdio.h> 

error = rawcon( f lag) ; 

int error; /* 0 on success */ 

int flag; /* non-zero for raw, 0 for non-raw */ 

This routine turns on and off the capability of stdin that allows you to 
get single character input without waiting for a new line character. 

This routine works with the getch and get char functions. Normally, 
the Amiga console device waits until you press the Return key before it 
passes the keystrokes you enter to your program. Therefore, the 
get char function, for example, will not be able to read a single 
character at a time. Calling rawcon ( 1 ) forces the console device to pass 
each character separately. Calling the rawcon ( 0 ) function restores the 
console to normal operations. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

AmigaDOS 

A nonzero return value indicates failure. 

/* 

* 

* Wait for user to press any key (if possible) 


*/ 

((include <stdio.h> 
((include <stdlib.h> 
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rawcon Set or unset raw console input 
( continued ) 


void main(void) 

I 

if (!rawcon(1)) 

( 

printf ( "Press any key to continue\n" ) ; 

/* make sure output from printf is seen */ 
f flush ( stdout) ; 
getchar ( ) ; 
rawcon( 0) ; 


else 

{ 

/* unable to switch the console, wait some other way */ 
printf ( "Sorry, rawcon() didn't work!\n"); 
exit (EXIT-FAILURE) ; 


) 

See Also getch, getcha: 
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rbrk 

Synopsis 

Description 

Portability 
Returns 
See Also 


Release memory 
Sinclude <stdlib.h> 
error = rbrk( void) ; 

int error; /* 0 if successful */ 

The rbrk function returns all memory in the memory pool, including 
level 2 I/O buffers, to the operating system. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

OLD 

This function returns 0 if successful, 
getmem, lsbrk, malloc, sbrk 
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read 

Synopsis 


Description 


Portability 

Returns 

See Also 


Read from a level 1 file 

((include <fcntl.h> 

count = read(fh, buffer, length) ; 

int count; /* actual bytes read or written */ 

int fh; /* file handle */ 

void *buffer; /* data buffer */ 

unsigned int length; /* number of bytes to read or write */ 

This function reads a level 1 file whose handle was returned by the 
creat or open function. Under normal circumstances, the value 
returned should match the buffer length. If this value is — 1 or greater 
than the requested length, then some type of error occurred, and you 
should consult the external integers err no and _OSERR. If the actual 
length is less than the requested length when reading, this usually means 
that the file is exhausted. It is a good idea to check the external integers 
errno and _OSERR just in case some malfunction caused the short 

count. Level 1 files are automatically closed by the exit and exit 

functions, which are usually called for you when the program terminates. 

Note: When using short integers (shortintegers compiler option), 
the maximum length that can be read is 65,536 (64 megabytes). With 
normal 32-bit integers, the maximum is 4 gigabytes (UINT_MAX). 

UNIX 

If the operation is successful, the function returns the actual number of 
bytes transferred. Otherwise, it returns — 1 and places error information 
in the external integers errno and _OSERR. 

close, errno, _OSERR, open, write 
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readdir 

Synopsis 


Description 


Portability 

Returns 


Read a directory element 
jfinclude <sys/dir.h> 
dptr = readdir(dfd) ; 

struct dirent *dptr; /* pointer to a directory entry */ 

DIR *dfd; /* directory file descriptor */ 

This function returns the next directory entry for a given directory. The 
df d argument is the directory file descriptor obtained from a call to the 
opendir function, and the dptr argument is the directory entry. A 
directory entry has the following format: 

struct dirent ( 

u_long d_ino; /* inode number of entry */ 

u_short cLreclen; /* length of this record */ 

u_short cLnamlen; /* length of string in d_name */ 

off_t d_off; /* offset of disk directory entry */ 

char cLname [ MAXNAMLEN+ 1 ] ; /* maximum length of name */ 


UNIX 

This function returns a pointer to a struct dirent, which is the next 
directory entry. If the readdir function reaches the end of the directory 
list or if an error occurs, a value of NULL is returned. For errors, the 
error information is placed in the external integers errno and _OSERR. 


See Also closedir, opendir, seekdir, telldir 
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readlocale Read and initialize a new locale 
Synopsis jjinclude <locale.h> 

ret = readlocale(locale) ; 

struct locale *ret; /* Pointer to the read locale or NULL */ 

const char *locale; /* Identifies the type of environment */ 


Description This function reads a new locale and initializes the memory for it. It finds 
this locale by first examining the LOCALE environment variable for the 
location of a base LOCALE directory. It attempts to open a file with the 
name pointed to by the locale argument. 

Portability SAS/C 

Returns This function returns a value of NULL if the locale is missing or invalid. 

Example ifinclude <stdlib.h> 

(finclude <locale.h> 

void main(void) 

( 

struct locale *lcl; 

if ( lcl=readlocale(NULL) )==NULL) 

( 

printf ( "Locale environment variable not set.\n"); 
exit( 1 ) ; 

) 

/* locale is set up */ 
exit(O) ; 

} 


See Also 


setlocale 
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realloc 

Synopsis 


Description 


► Caution 
Portability 
Returns 

See Also 


Reallocate memory 
jfinclude <stdlib.h> 
nb = realloc(b,n) ; 


void 

*b; 

/* 

block pointer 

*/ 

void 

*nb; 

/* 

new block pointer 

*/ 

size. 

_t n; 

/* 

number of bytes 

*/ 


A call to the realloc function gets a new block of memory whose size 
is n bytes. Then, it copies the old block b to the new block nb and 
releases the old block. If it is less than the old block size, only the first n 
bytes are copied. If b is NULL, a new block of size n is allocated and 
returned. If b is NULL and the size is 0, a NULL pointer is returned. 

Under certain circumstances, you can reallocate a block that has been 
freed. The free function releases a block that was previously obtained 
with the calloc, malloc, or realloc function. For compatibility with 
some versions of UNIX, the block is not actually returned to the free 
space pool until the next time you call the calloc, malloc, realloc, 
or free function. Then, if that next call is to the realloc function and 
the block being reallocated is the one that was just freed, the realloc 
function will proceed correctly. In other words, you can ask the 
realloc function to reallocate a block that was freed as long as you 
have not called the calloc, malloc, or realloc function in the 
meantime. 

If you are compiling with short integers, the realloc function can 
only allocate 64 kilobytes at a time. 

This function is called a level 3 memory allocation function because it 
calls on the level 2 function getmem. This level is fully compatible with 
UNIX and with the ANSI standard. 

The level 1 function rbrk frees all level 2 and level 3 blocks. A 

ANSI 

The realloc function returns a NULL pointer if there is not enough 
space for the requested block. In this case, the original block b is 
unchanged. 

calloc, free, getmem, malloc, rbrk, rlsmem, sbrk 
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remove Remove a file 
Synopsis # include <stdio.h> 

error = remove ( name ) ; 

int error; /* non-zero if error */ 

const char *name; /* file name */ 


Description This function removes the specified file from the system. 

The filename argument can include a path, but it cannot include wild 
card characters. That is, you can remove only one file at a time. 

Portability ANSI 

Returns If a nonzero value is returned, some type of error occurred, and 

additional information can be found in the external integers err no and 
_OSERR. The most common errors occur when you try to remove a file 
that doesn’t exist, that is marked as read-only, or is in use. 

Example This program removes all files specified in the argument list. It does not 
allow wildcard characters in the filenames. 


iinclude <stdio.h> 

Sinclude <stdlib.h> 

void main(int argc, char *argv[]) 

( 

int i; /* loop counter */ 

/* exit code, non-zero if any failures */ 
int ret = EXIT_SUCCESS; 

for (i = 1; i < argc; i++) 

( 

if (remove(argv[i] ) ) 

{ 

perror ( "RMV" ) ; 
ret = EXIT-FAILURE; 

i 




exit(ret) ; 



C Library Reference 397 


remove Remove a file 
(continued) 


See Also errno, _OSERR, unlink 



398 Chapter 7 


rename 

Synopsis 


Description 

Portability 

Returns 

Example 


Rename a file 
((include <stdio.h> 
error = rename (old, new ) ; 

int error; /* 0 for success, nonzero for error */ 

const char *old; /* old file name */ 

const char *new; /* new file name */ 

This function renames a file, if possible. The old name can include a path, 
but the new name should not. This function fails if it cannot find the old 
file or if the new name is the same as an existing file. 

ANSI 

If the function fails, it returns a nonzero integer and places additional 
error information into the external integers errno and _OSERR. If it is 
successful, it returns a 0. 

/* 

* 

* This is a version of the rename command 

* that prompts for the old and new names. 

* 

*/ 

((include <stdio.h> 

((include <stdlib.h> 

((include <fcntl.h> 

)f include <dos.h> 

void main(int argc, char *argv[]) 

( 

char oldJFMSIZE] ,new[FMSIZE] ; 
char *pold,*pnew; 
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rename Rename a file 
(continued) 


if (argc < 2) /* Get old file name 

{ 

printf ( "OLD FILE: "); 
if (fgets(old,sizeof (old) ,stdin) = 
{ 

exit ( EXIT-FAILURE ) ; 

) 

old[strlen(old)-1 ] = '\0'; 
pold = old; 


else 

( 

pold = argv[ 1 ] ; 

) 

if (argc < 3) 

{ 

printf ("NEW FILE: "); 
if (fgets(new,sizeof (new) ,stdin) = 
{ 

exit ( EXIT-FAILURE ) ; 

) 

new(strlen(new)-1 ] = '\0'; 
pnew = new; 


else 

( 

pnew = argv[ 2 ) ; 

) 


if (rename(pold,pnew) ) 

{ 

perror ( "RENAME" ) ; 
exit ( EXIT-FAILURE ) ; 


*/ 

= NULL) 


= NULL) 
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repmem 

Synopsis 


Description 


Portability 

Example 


Replicate values through a block 

((include <string.h> 

void repmem( to , vt , nv , nt ) ; 


void *to; 
const void *vt; 
size_t nv; 
size_t nt; 


/* destination pointer */ 

/* value template */ 

/* number of bytes in template */ 
/* number of templates in block */ 


This function repeats a template of values throughout a block. It is very 
useful when you need to initialize an array of structures to some nonzero 
pattern. 

This function neither recognizes nor produces the NULL terminator 
byte usually found at the end of strings. 

This function is not available if the _STRICT__ANSI flag has been 
defined. 

SAS/C 


/* 

* Initialize an array of structures 
*/ 

((include <stdio.h> 

((include <string.h> 

struct XMP 

( 

int x; 
double d; 

}; 


struct XMP xmp[200]; 

void initxmp( void) 

( 

xmp[ 0 1 . x= 1 0 ; 
xmp[0] . d=20 . 0 ; 


) 


/* All elements are now initialized to 10 and 20.0 */ 
repmem(6xmp[ 1] ,Sxmp[0] , sizeof ( struct XMP) ,199) ; 
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repmem Replicate values through a block 
(continued) 


void main(void) 

( 

initxmp( ) ; 

printf ( "xmp[0] .x = ftd, xmp[0].d = 551f\n", 
xmp [ 0 ] . x , xmp [ 0 ] . d ) ; 

printf ( "xmp[ 199] .x = %d, xmp[199].d = JSlfNn", 
xmp[199].x, xmp[199].d); 
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rewind Reset a level 2 file position to its first byte 
Synopsis § include <stdio.h> 
void rewind(fp); 

FILE *fp; /* file pointer */ 

Description The rewind function resets the specified file to its first byte and is 
equivalent to the following fseek call: 

fseek{fp,0L,0) ; 

The rewind function also clears the error indicator on the file. 

The rewind function is implemented as a macro that calls the fseek 
function. 


Portability ANSI 

See Also errno, fopen, fseek, lseek, _OSERR, tell 
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rewinddir Reset to the start of the directory 
Synopsis jj include <sys/dir.h> 
void rewinddir (dfd) ; 

DIR *dfd; /* dir file descriptor */ 

Description This macro changes the position from which the readdir function will 
read the next directory entry, resetting the current position to the start of 
the directory. The dfd argument is a directory file descriptor returned 
from a successful call to the opendir function. 

The rewinddir function is guaranteed only for the life of the 
directory file descriptor. If a directory is closed and reopened, the 
directory entry locations may be invalid. 

The rewinddir function is implemented as a macro that calls the 
seekdir function as follows: 

seekdir (dfd, ( long) 0 ) ; 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability UNIX 

See Also closedir, opendir, readdir, seekdir, telldir 
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rlsmem 

Synopsis 


Description 


Portability 
See Also 


Release a memory block 
((include <stdlib.h> 
void rlsmem(p, sbytes ) ; 

void *p; /* block pointer */ 

unsigned int sbytes; /* number of bytes */ 

This function releases memory blocks that were previously obtained with 
the getmem or getml function. If the number of bytes is less than the 
value MELTS IZE as defined in header file dos . h, then it is made equal 
to MELTSIZE. 

If you compile with short integers, the rlsmem function will free only 
64 megabytes or less of memory. 

This function is equivalent to the free function. The second parameter 
is ignored. The rlsmem function is included for compatibility with 
previous versions of the compiler. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

OLD 

free, rlsml 
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rlsml 

Synopsis 


Description 


Portability 


Release a memory block 

({include <stdlib.h> 

void rlsml ( p , lbytes ) ; 

void *p; /* block pointer */ 

long lbytes; /* number of bytes */ 

This function releases memory blocks that were previously obtained with 
the getmem or getml function. 

This function is equivalent to the free function. The second parameter 
is ignored. The rlsml function is included for compatibility with 
previous versions of the compiler. 

This function is not available if the _STRICT__ANSI flag has been 
defined. 

OLD 


See Also 


free, rlsmem 
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rmdir 

Synopsis 


Description 

Portability 

Returns 


Remove a directory 
((include <dos.h> 
error = rmdir(path); 

int error; /* 0 if successful */ 

const char *path; /* points to directory path string */ 

This function removes an existing directory in the specified path. For 
example, if the path is sys:/abc/def/ghi, then the directory named 
ghi is removed from the path /abc/def on the system drive. For 
AmigaDOS, the path may begin with a drive or volume name and a 
colon. 

UNIX 

If the operation is successful, the function returns 0. Otherwise, it 
returns —1 and places error information in the external integers err no 
and _OSERR. 


See Also errno, mkdir, _OSERR 



C Library Reference 407 


rstmem 

Synopsis 

Description 

Portability 
See Also 


Reset the memory pool 
((include <stdlib.h> 
void rstmem( void) ; 

It is recommended that you use the getmem and rlsmem functions or 
the malloc and free functions instead of this function. The rstmem 
function is provided for compatibility with previous releases. 

This function is not available if the _strict_ansi flag has been 
defined. 

OLD 

getmem, getml, rlsmem, rlsml, sizmem 
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sbrk 

Synopsis 


Description 

Portability 

Returns 


Allocate memory (unsigned) 

((include <stdlib.h> 
p = sbrk(sbytes) ; 

void *p; /* block pointer */ 

unsigned int sbytes; /* number of bytes */ 

The sbrk function is provided for compatibility with previous releases of 
the compiler. Use the malloc function instead. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

OLD 

If successful, this function returns the address of the block just allocated. 
If the sbrk function fails, it returns value (char * ) ( - 1 ) , which is —1 
cast into a character pointer. 


See Also getmem, lsbrk, malloc 
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scant 

Synopsis 


Description 

Portability 

Returns 


Formatted input conversions 
jfinclude <stdio.h> 
n = scant (fmt,arg1 ,arg2 , ...) • 

int n; /* number of input items matched, or EOF */ 

const char *frat; /* format string */ 

*argx; /* pointers to input data areas */ 

This function performs formatted input conversions on text obtained from 
the standard input file. 

This function works like the f scanf function. See the description of 
the f scanf function earlier in this chapter for a complete description. 

ANSI 

The function returns the number of assignments that were made. For 
example, a return value of 3 indicates that conversion results were 
assigned to the arguments argl, arg2, and arg3. 


See Also f scanf, sscanf 
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SCdir Return the name of the next file matching pattern 
Synopsis i include <f unctions .h> 

buffer = scdir(char *pattern); 


static char *buffer; /* buffer containing filename */ 

char *pattern; /♦ file pattern to parse */ 

Description This function returns the next filename that matches the pattern you 
specify. The only wildcards that scdir recognizes are the UNIX 
wildcards * and ?. 

Portability OLD 

Returns This function returns a pointer to the buffer that contains the next 

matching filename, scdir overwrites this buffer each time it is called. 


See Also dfind, dnext, getfnl 
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SCF ... Screen control functions 

Synopsis # include <scrcntl.h> 

void scr_beep( void) ; /* calls Intuition DisplayBeep */ 

void scr_bs ( void) ; /* moves cursor left one position */ 

void scr_cdelete( void) ; /* deletes character under cursor */ 

void scr_cinsert( void) ; /* inserts blank at cursor */ 

void scr_clear( void) ; /* clears window */ 

void scr_cr (void) ; /* causes a carriage return */ 

void scr_curs(int line, int column); /* moves cursor to specified */ 

/* line/column */ 

void scr_cursrt( void) ; /* moves cursor right one character */ 

void scr_cursup( void) ; /* moves cursor up one line */ 

void scr_eol( void) ; /* erases from cursor to end-of-line */ 

void scr_home( void) ; /* moves cursor to upper left */ 

void scr_ldelete( void) ; /* deletes line at cursor position */ 

void scr_lf ( void) ; /* moves cursor down one line */ 

void scr_linsert ( void) ; /* inserts blank line at cursor */ 

void scr_tab( void) ; /* moves cursor right one tab stop */ 

Description The following list describes each of these screen control functions. 

scr_beep calls the Intuition function DisplayBeep. 

scr_bs moves the cursor left one character position without 
modifying any characters. 

sc r_c delete deletes the character under the cursor and shifts the 
rest of line left one position. 

scr_c insert shifts the line to the right and inserts a blank under the 
cursor. 

scr_clear clears the window and moves the cursor to the upper 
left (the home position). 
scr_cr causes a carriage return. 
scr_curs moves the cursor to specified line and column. 
scr_cursrt moves the cursor right one character without modifying 
any characters. 

scr_cursup moves the cursor up one line without changing its 
column or modifying any characters. 
scr_eol erases from the cursor position to the end-of-line. 
scr_home moves the cursor to the upper left corner of window 
without modifying any characters. 
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SCr_... Screen control functions 
( continued ) 


scr_ldelete 

scr_lf 

scr_linsert 

scr_tab 


deletes the line at the cursor position. 

moves the cursor down one line. If the cursor is on the 

bottom line in the window, this function scrolls the file. 

inserts a blank line at the cursor position. 

moves the cursor to the right one tab stop. 


You can achieve the same functionality by printing standard ANSI 
X3.64 console control codes to the console window. For example, to 
make the terminal beep, you can print the BEL character (\x0 7) instead 
of calling scr_beep. 


Portability OLD 


See Also 


control sequences in Amiga ROM Kernel Reference Manual: Devices 
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seed48 

Synopsis 


Description 


Portability 

Returns 


Set all 48 bits of an internal seed 
<| include <math.h> 
pseed = seed48 ( seed) ; 

unsigned short seed [ 3 ] ; /* seed value (high bits in seed[0]) */ 
unsigned short *pseed; /* pointer to internal seed */ 

This function generates random numbers using the linear congruential 
algorithm and 48-bit arithmetic. 

The seed 4 8 function allows you to initialize the internal 48-bit seed to 
something other than the default. The entire 48 bits are loaded from the 
specified array. 

See the lcong48 function for additional information. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

This function returns a pointer to the internal seed array. 


See Also lcong48, rand, srand, srand48 
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seekdir 

Synopsis 


Description 


Portability 


Reposition a directory operation 
((include <sys/dir.h> 
void seekdir(dfd, loc ) ; 

DIR *dfd; /* dir file descriptor */ 

long loc; /* entry location */ 

This routine changes the position from which the readdir function will 
read the next directory entry. The df d argument is a directory file 
descriptor returned from a successful call to the opendir function. The 
loc argument is a directory entry location as returned from a call to the 
telldir function. 

Seek locations are guaranteed only for the life of the directory file 
descriptor. If a directory is closed and reopened, the directory entry 
locations may be invalid. 

UNIX 


See Also closedir, opendir, readdir, rewinddir 
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setbuf 

Synopsis 


Description 


Portability 
See Also 


Set the buffer mode for a level 2 file 

finclude <stdio.h> 

void setbuf ( fp,buff ) ; 

FILE *f p ; /* file pointer */ 

const char *buff; /* buffer pointer */ 

This function sets the buffering mode for a level 2 file. You should call 
this function after calling the f open function and before calling any 
other level 2 I/O functions. If you do not call this function in the correct 
sequence, the file may become corrupted. Do not allocate a buffer on the 
stack within a function, attach it to a file, and then return from the 
function. This will corrupt the stack and cause a system failure. 

The level 2 I/O system automatically allocates a buffer using the 
getmem function when you perform the first read or write operation. 
Then, the data being read or written are staged through this buffer to 
improve I/O efficiency. If you would rather use your own buffer instead 
of having one allocated for you, call the setbuf function with a non- 
NULL buffer pointer. The buffer size must be at least as large as the 

value given in the external integer buffsize, which defaults to the 

value of the symbol BUFSIZ, defined in the file stdio.h. 

You can eliminate buffered I/O by calling the setbuf function with a 
NULL buffer pointer. When this is done, physical I/O occurs whenever 
your program performs a level 2 read or write operation, even if only 
one byte is being transferred. This is very inefficient for disk files but 
often desirable for terminal or communication ports. 

ANSI 

fopen, setnbf, setvbuf 
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setjmp 

Synopsis 


Description 


Portability 

Returns 

Example 


Set long jump parameters 

Hinclude <setjmp.h> 

ret = set jmp( save) ; 

int ret; /* return code */ 

jmp_buf save; /* address of save area */ 

The setjmp function saves the current stack mark in a specified save 
area and returns a code of 0. A subsequent call to the longjmp function 
with the same save area causes control to return to the next statement 
after the original setjmp call. In other words, the statement immediately 
after the setjmp call will be executed twice, once after you call the 
setjmp function and once after you call the longjmp function. 

Do not use the longjmp function after the function calling setjmp 
has returned to its caller. This cannot possibly succeed, because the stack 
frame for that function no longer exists. 

This mechanism is useful for quickly popping up through multiple 
layers of function calls under exceptional circumstances. 

From within a shared library, you must not call any library functions 
that terminate your program. For example, you cannot call exit, 

exit, or abort from a shared library. You also cannot use setjmp 

and long jmp to jump across a call from the program into the library. 

ANSI 

A return code of 0 from the setjmp function indicates that this is the 
initial call to save the stack. A nonzero return code indicates that the 
longjmp function has been executed. 

iinclude <stdio.h> 
jfinclude <setjmp.h> 

jmp_buf save; 

void foo(void) 

( 

long jmp( save, 1); 

} 

void main(void) 

( 


int ret; 
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setjmp Set long jump parameters 
(continued) 


ret=setjmp(save) ; 

if ( ret==0 ) 

{ 

/* setjmp has been called, but not longjmp */ 
foo( ) ; 

) 

else 

( 

/* longjmp has been called */ 
printf("all done\n"); 

} 


See Also longjmp 
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setlocale Set locale information for a program 
Synopsis ((include <locale.h> 

ret = setlocale(category, locale); 

char *ret; /* Pointer to the selected locale portion */ 

int category; /* Names the portion of the locale to be */ 

/* selected */ 

const char *locale; /* Identifies the type of environment */ 

Description This function selects the appropriate portion of the program’s locale as 

specified by the category and locale arguments. The category argument 
indicates which portion of a program’s locale will be affected. You must 
specify one of the following values: 

Value Portion Affected 

LC—COLLATE the behavior of the strcoll and strxfrm functions 
LC—CTYPE the character-handling and multibyte functions 

LC—NUMERIC the decimal point character for the formatted I/O and 
string conversion functions, and the nonmonetary 
formatting information returned by the localeconv 
function 

LC—TIME the behavior of the strftime function 

LC—MONETARY the monetary formatting information returned by the 
localeconv function 


LC—ALL 


the entire program’s locale 
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setlocale Set locale information for a program 
(continued) 

The locale string, which identifies the type of environment to use, 
may contain one of three special values: 

Value Meaning 

C Use the minimal environment for C translation. 

" " Use the Amiga native environment. 

null Use the current default locale without changing 
it. 


If the locale argument is not one of these strings, the setlocale 
function searches its internal list of locale environments for a matching 
one. If it finds one, it uses it. Otherwise, it attempts to open a disk-based 
locale specification by using the readlocale function. 

Portability ANSI 

Returns If it finds the selected environment, the setlocale function returns a 

pointer to a string associated with the requested category. If it cannot find 
the environment, it returns a NULL pointer, and the program’s locale is 
not changed. This string is considered read-only and is valid until the 
next call to the setlocale function. 


See Also localeconv, readlocale 
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setmem 

Synopsis 


Description 


Portability 
See Also 


Set a memory block to a value 

Hinclude <string.h> 

void setmem(to,n,c) ; 

void *to ; /* destination pointer */ 

unsigned n; /* number of bytes */ 
int c; /* character value */ 

This function sets blocks of memory to a value. It neither recognizes nor 
produces the NULL terminator byte usually found at the end of strings. 

This function is similar to the built-in function memset, which is an 
ANSI function. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

memset, repmem 
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setnbf 

Synopsis 

Description 


Portability 


Turn off I/O buffering for level 2 file 
{(include <stdio.h> 
void setnbf (fp) ; 

FILE *fp; /* file pointer */ 

This function eliminates buffered I/O for a level 2 file. You should call 
this function after calling the f open function and before calling any 
other level 2 I/O functions. If you do not call this function in the proper 
sequence, the file may become corrupted. 

After you call the setnbf function, physical I/O occurs whenever 
your program performs a level 2 read or write operation, even if only 
one byte is being transferred. This is very inefficient for disk files but 
often desirable for terminal or communication ports. 

This function is equivalent to: 

setbuf ( fp ,NULL ) ; 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 


See Also f open, setbuf, setvbuf 
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Setvbuf Set the buffer mode for a level 2 file 
Synopsis ((include <stdio.h> 


error = setvbuf (fp,buff, type, size) ; 


int error; 

/* 

0 if successful */ 

FILE *f p ; 

/* 

file pointer */ 

const char *buff; 

/* 

buffer pointer */ 

int type; 

/* 

type of buffering *. 

size_t size; 

/* 

buffer size in byte: 


Description This function sets the buffering mode for a level 2 file. You should call 
this function after calling the fopen function and before calling any 
other level 2 I/O functions. If you do not call this function in the correct 
sequence, the file may become corrupted. Do not allocate a buffer on the 
stack within a function, attach it to a file, and then return from this 
function. This sequence will corrupt the stack and cause a system failure. 

The level 2 1/0 system automatically allocates a buffer using the 
getmem function when you perform the first read or write operation. 
Then the data being read or written are staged through this buffer to 
improve I/O efficiency. If you would rather use your own buffer instead 
of having one allocated for you, call the setvbuf function with a non- 
NULL buffer pointer. The buffer size must be at least as large as the 

value given in the external integer buffsize, which defaults to the 

value of the symbol BUFSIZ, defined in the file stdio . h. 

The setvbuf function can set line-buffered mode, attach a buffer of 
nonstandard size, or turn off buffering. The type argument must be one 
of the following symbols defined in the file stdio . h: 


Type Meaning 

— IOFBF fully buffered 

IOLBF line buffered 

— IONBF nonbuffered 

For the _I0FBF and —IOLBF symbols, the specified buffer is attached 
to the file unless the buff argument is NULL, in which case a buffer is 
automatically allocated on the first read or write. For the —IONBF 
symbol, the buff and size arguments are ignored. 
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setvbuf 

(continued) 


Portability 

Returns 

See Also 


Set the buffer mode for a level 2 file 


The line-buffered mode is useful for interactive applications. When in 
this mode, the buffer is flushed whenever a new line is sent, the buffer is 
full, or input is requested. However, you must use the f putc and 
f put char functions instead of the putc and put char macros for line 
buffering to work correctly. The macros do not check if line-buffered 
mode is active, so they behave as if the file were fully buffered. 

ANSI 

The setvbuf function returns a nonzero error code if type or size is 
invalid. 

fopen, setbuf, setnbf 
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signal 

Synopsis 


Description 


Establish event traps 

({include <signal.h> 

oldfun = signal ( sig, newfun) ; 

void (*oldfun) (int ) ; /* old trap function */ 

int sig; /* signal number */ 

void (*newfun) (int) ; /* new trap function */ 

This function establishes traps for various events that can occur outside 
of your program. 

The new fun argument specifies the action to be taken when the signal 
occurs, as follows: 

SIG—IGN ignore the signal. 

SIG—DFL take the system default action, as indicated above for each 
signal. 

If the newf un argument is not either of the above, then it must be a 
valid function pointer. When the signal is detected, the action is reset to 
either sig_dfl or SIG—IGN, depending on the particular signal. Then, 
the trap function is called with an integer argument specifying which 
signal was detected (for example, SIGINT). The trap function can take 
whatever action is necessary, including calling the signal function again 
to re-establish itself as the trap function. If the function returns, 
execution continues at the point in your program where the signal was 
detected. 

The sig argument specifies which signal is being trapped, using the 
following symbols defined in the file signal . h: 

S IGF PE occurs whenever a floating-point error is detected and the 
standard version of the CXFERR function is installed. If you 
install your own version, you must duplicate our code 
(supplied as a file named CXFERR . C) to provide this signal. 
SIGINT occurs whenever the user operates the Control-C or Control-D 
key combination. The default action for AmigaDOS is to abort 
your program. If you specify a function to be called, the signal 
is reset to SIG_IGN when the interrupt occurs. Your function 
should call the signal function again if you want to reinstall 
the trap. 


Portability ANSI 
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signal Establish event traps 
(continued) 

Returns If the trap can be established, the signal function returns a pointer to 
the previous handler function. Otherwise, it returns the value SIG—ERR 
and places error information in the external integer err no. 
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Sin Sine function 
Synopsis jf include <math.h> 
r = sin(x) ; 

double r; /* result */ 

double x; /* angle */ 


Description The sin routine computes the sine of an angle expressed in radians. 
Portability ANSI 


See Also cos, cosh, matherr, sinh 
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sinh 

Synopsis 


Description 


Portability 


Hyperbolic sine function 
ffinclude <math.h> 
r = sinh(x) ; 

double r; /* result */ 

double x; /* angle */ 

The sinh routine computes the normal hyperbolic sine of an angle. A 
range error occurs if the hyperbolic sine is too large to be represented by 
a double-precision floating-point number. 

ANSI 


See Also cos, cosh, matherr, sin 
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sizmem 

Synopsis 

Description 


Portability 
See Also 


Get memory pool size 
finclude <stdlib.h> 
size = sizmem( void) ; 
long size; 

This function returns the number of unallocated bytes in the current 
memory pool. This value is the sum of the sizes of all unallocated blocks, 
so it does not indicate the size of the largest free block. 

Also, the value does not indicate the maximum amount of memory that 
can be allocated. That is, the allocation functions will automatically 
expand the pool when no block of sufficient size is found in the pool. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

getmera, getml, rlsraem, rlsml, rstmem 
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sprintf 

Synopsis 

Description 

Portability 

Returns 

Example 


Formatted print to a string 
((include <stdio.h> 


length = sprintf (s,fmt,arg1,arg2, ...) ; 


int length; 

/* 

char *s; 

/* 

const char *fmt; 

/* 

type argx; 

/* 


number of characters generated */ 
pointer to a character string */ 
format string */ 
arguments */ 


This function produces an output stream of ASCII characters and sends 
the output to the storage area whose address is given by the argument s. 
Make sure that this area is large enough to hold the maximum number of 
characters that might be generated. The sprintf function also generates 
a NULL byte to terminate the stored string. 

This function works like the f print f function. See the description of 
the fprintf function earlier in this chapter for a complete description. 

ANSI 

This function returns the number of output characters generated. This 
number does not include the terminating null byte. 

/* 

* This example prints a message indicating whether 

* the function argument is positive or negative. 

* In the second printf, the width and precision 

* are 15 and 8, respectively. 

*/ 

((include <stdio.h> 


void pneg(double value) 

{ 

char *sign, buff [256); 

if (value < 0) sign = "negative"; 
else sign = "not negative"; 

sprintf (buff , "The number XE is )Ss.\n", 
value, sign) ; 
printf (buff ) ; 
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Sprintf Formatted print to a string 
(continued) 


sprintf (buff , "The number is fts.Nn", 

15, 8, value, sign) ; 
printf (buff ) ; 

) 


void main(void) 

{ 

pneg(37.8) ; 
pneg(-18.2) ; 

) 


See Also fprintf, printf 
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sqsort 

Synopsis 


Description 

Portability 


Sort an array of short integers 
((include <stdlib.h> 
void sqsort(sa,n) ; 

short *sa; /* pointer to short int array */ 
size_t n; /* number of elements in array */ 

The sqsort function sorts the specified array of short integers using the 
ACM 271 algorithm, more popularly known as Quicksort. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 


See Also dqsort, f qsort, lqsort, qsort, tqsort 
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sqrt 

Synopsis 

Description 

Portability 
See Also 


Square root function 
({include <raath.h> 
r = sqrt(x ) ; 
double r, x; 

The sqrt function calculates the square root of a number. The number 
must be a positive argument. If you supply a negative argument, the 
matherr function will be called with a DOMAIN error. 

ANSI 

matherr, pow, pow2 
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Srand Set the seed for the rand function 
Synopsis # include <stdlib.h> 
void srand(seed); 

unsigned int seed; /* random number seed */ 

Description The srand function resets the random number generator to a new seed 
value. The initial default seed is 1. 

Portability ANSI 

Example /* This example prints 1000 random numbers */ 
iinclude <stdio.h> 
finclude <stdlib.h> 

void main(int argc, char *argv[]) 

{ 

int i, x; 

if (argc > 1 ) 

{ 

stcd_i ( argv[ 1 ] , Sx) ; 
if (x == 0) 

( 

x = 1; 

} 

printf("Seed value is $d\n",x); 
srand(x) ; 

) 

printf ( "Here are 1000 random numbers ... \n" ) ; 
for (i = 0; i < 200; i++) 

{ 

printf ("S5d % 5d £5d £5d fl5d\n", 

rand( ) ,rand( ) ,rand( ) ,rand( ) ,rand( ) ) ; 

) 

printf ( "\n" ) ; 


See Also drand48, erand48, jrand48, lrand48, nrand48, rand, srand48 
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srand48 

Synopsis 


Description 


Portability 


Set high 32 bits of an internal seed 
((include <math.h> 
void srand48(hseed) ; 

long hseed; /* high 32 bits of seed value */ 

The srand48 function allows you to initialize the internal 48-bit seed 
used by the functions drand48, erand48, lrand48, nrand48, and 
jrand4 8. The value you specify is copied into the high 32 bits of the 
seed, and the low 16 bits are set to 0x3 3 0E. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 


See Also lcong48, rand, seed48, srand 
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SSCanf Formatted input conversions 
Synopsis ((include <stdio.h> 

n = sscanf (ss,fmt,arg1 ,arg2, ...) ; 


int n; 

const char *ss; 
const char *fmt; 
*argx; 


/* number of input items matched, or EOF */ 
/* input string (sscanf only) */ 

/* format string */ 

/* pointers to input data areas */ 


Description This function performs formatted input conversions on text obtained from 
a string. 

This function works like the f scanf function. See the description of 
the f scanf function earlier in this chapter for a complete description. 

Portability ANSI 


Returns This function returns the number of assignments that were made. For 
example, a return value of 3 indicates that conversion results were 
assigned to the arguments argl, arg2, and arg3. 
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stackavail 

Synopsis 

Description 

Portability 

Returns 


Get current available stack size 

({include <dos.h> 

size = stackavail( void) ; 
unsigned long size; 

This function calculates the amount of stack that is currently available. 
This function will not work in a shared library and is not reliable if you 
compile with the stackext option. 

SAS/C 

This function returns the number of bytes that are currently available on 
the stack. 
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stacksize 

Synopsis 

Description 

Portability 

Returns 

Example 


Get the current stack size 
((include <dos.h> 
size = stacksize(void) ; 

unsigned long size; /* size of current stack */ 

This function calculates the size of the current stack and returns its size 
in bytes. This function will not work in a shared library and is not 
reliable if you compile with the stackext option. 

SAS/C 

This function returns the number of bytes available for the entire stack 
when the program was started. 

/* 

* Ensure at least 8K is available for certain 

* operations 
*/ 

{(include <stdio.h> 

((include <dos.h> 

void main(void) 

( 

char *amount; 

if ( stacksize( ) > 8000 ) 

{ 

/* Do the operation */ 

amount = "More than 8000 bytes"; 

) 

else 

{ 

/* Tell users it is not safe to do it */ 
amount = "8000 bytes or less"; 

) 

printf("Ss stack available. \n" , amount); 

) 


See Also 


stack 
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stackused 

Synopsis 

Description 

Portability 

Returns 


Get the amount of stack in use 

({include <dos.h> 

size = stackused( void) ; 

unsigned long size; /* amount of current stack in use */ 

This function calculates the amount of the current stack currently in use 
and returns the amount in bytes. This function will not work in a shared 
library and is not reliable if you compile with the stackext option. 

SAS/C 

This function returns the number of bytes of stack currently being used. 


See Also stack 
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Stat Get information on a file 

Synopsis # include <sys/stat.h> 

rc = stat(file, st) ; 

int rc; /* return code */ 

const char *file; /* file name */ 

struct stat *st; /* stat info structure */ 

Description This function obtains information for the given file. If the file is not in 
the current directory, the file path must be included as part of the 
filename. Permission to read, write, or execute the file is not required. 

This function is provided for compatibility with UNIX. For code that 
will be used only on the Amiga, use the AmigaDOS function Examine 
instead. 

The information is placed into the stat structure pointed to by the 
st argument. The structure is defined in the file stat . h and contains 
information as follows: 

struct stat { 


unsigned 

short 

st_mode; 

/* 

file mode */ 

ino_t 


st_ino; 

/* 

inode number */ 

dev_t 


st_dev; 

/* 

file system identifier */ 

char 


*st_rdev; 

/* 

device ID (volume name) */ 

short 


st_nlink; 

/* 

number of links */ 

unsigned 

short 

st_uid; 

/* 

file owner user-id */ 

unsigned 

short 

st_gid; 

/* 

file group user-id */ 

of f_t 


st_size; 

/* 

file size in bytes */ 

time_t 


st_atime; 

/* 

time last accessed */ 

time_t 


st_mtime ; 

/* 

time last modified */ 

time_t 


st_ctime; 

/* 

time last status change */ 

short 


st_type ; 

/* 

Amiga file type */ 

char 


*st_comment; 

/* 

Amiga file comment */ 


); 


st is a pointer to a stat structure that must be allocated on a 4-byte 
(long word) boundary by the calling program. A common error is failing 
to allocate the structure before calling the function. You can make sure 
the structure is long-word aligned by either declaring it with the 

aligned keyword or by allocating it dynamically with any SAS/C or 

system allocation function (such as the malloc or AllocMem function). 
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stat 

(continued) 

Get information 

on a file 


The following table lists defines that are combined with the logical OR 
operator to form the st_mode field. This list is found in both f cntl . h 
and stat . h. 


Symbol 

Meaning 


S ISCRIPT 

The object has its script protection bit set. 


S—IPURE 

The object is executable. 


S IARCHIVE 

The file has its archive bit set. 


S—IREAD 

The file is readable. 


S — I WRITE 

The file is writable. 


S_I EXECUTE 

The file is executable. 


S—IDELETE 

The file is deletable. 

Portability 

UNIX 


Returns 

If the operation is successful, the function returns 0. Otherwise, it 
returns —1 and places error information in the external integers err no 
and _OS ERR. 

See Also 

chmod, errno, 

f Stat, _ OSERR 
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Stcarg Get an argument 
Synopsis § include <string.h> 
length = stcarg(s,b); 


int length; 
const char *s; 
const char *b; 


/* number of bytes in argument */ 
/* text string pointer */ 

/* break string pointer */ 


Description This function scans the text string until it finds one of the break 

characters or the NULL terminating byte. While scanning, the stcarg 
function skips over substrings that are enclosed in single or double 
quotes, and the backslash is recognized as an escape character. Break 
characters will not be detected if they are quoted or preceded by a 
backslash. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


Portability SAS/C 

Returns The function returns a count of the number of characters in the argument 
s up to but not including the break character or NULL terminator. 

Example # include <stdio.h> 
jfinclude <stdlib.h> 

((include <string.h> 

void main(void) 

{ 

char a [ 256 ] , b [ 256 ] ; 
int x; 

while( 1 ) 

I 

printf ( "Enter text string: "); 

if (fgets(a,sizeof (a) ,stdin) == NULL) 

{ 


break; 
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stcarg Get an argument 
(continued) 


printf ( "Enter break string: "); 
if (fgets(b,sizeof (b) ,stdin) == NULL) 

{ 

break; 

) 

x = stcarg(a,b); 

printf ("Arg length: %d , Arg text: *s\n", 
x, a) ; 

) 

printf ( "\n" ) ; 


See Also stpbrk, strcspn, strpbrk 
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stccpy 

Synopsis 

Description 

Portability 

Returns 

Example 


Copy one string to another 
({include <string.h> 


size = stccpy(to, from,n) ; 


int size; 
char *to; 
const char *from; 
int n; 


/* number of bytes copied */ 
/* destination pointer */ 

/* source pointer */ 

/* maximum source length */ 


This function copies the NULL-terminated source string to the destination 
area. The stccpy function writes up to n characters to the destination 
and stops copying at the first occurrence of a NULL byte. The stccpy 
function always produces a NULL-terminated string. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


UNIX 

This function returns the actual number of bytes placed in the to area, 
including the NULL terminator. 

/* 

* This example prints: Hello, my name is Flo. 

*/ 

{{include <stdio.h> 

{{include <string.h> 

void main(void) 

{ 

char b[ 256 ) ; 

stccpy(b, "Hello, ",256); 

stccpy! fib[ strlen(b) ], "my name is " ,256-strlen(b) ) ; 
stccpy! fib [ strlen(b) ] , "Flo. " ,256-strlen(b) ) ; 
puts(b) ; 
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stcd_i 

Synopsis 


Description 


Portability 

Returns 

Example 


Convert a decimal string to an integer 

iinclude <string.h> 

length = stcd_i(in,ivalue) ; 

int length; /* input length */ 

const char *in; /* input string pointer */ 

int *ivalue; /* integer value pointer */ 

This function scans an input string and converts the leading characters 
into short integers. The input string must begin with a plus sign (+), 
minus sign ( — ), or a decimal digit (0 to 9). The stcd_i function stops 
scanning the input string when it reaches the first invalid character. At 
that point, the resulting value is stored in the area addressed by the 
second argument. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

This function returns the number of input characters converted. The 
result is 0 if the first character of the input string is not a valid decimal 
digit, a plus sign ( + ), or a minus sign ( — ). In that case, the conversion 
result pointed to by the second argument is 0. 

((include <stdio.h> 
iinclude <string.h> 

void main(void) 

{ 

int x; 
int j ; 
char b[80 1 ; 

while( 1 ) 

{ 

printf { "XnEnter a decimal value: "); 
if (fgets(b,sizeof (b) ,stdin) == NULL) 

( 


) 


break; 
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stcd_i Convert a decimal string to an integer 
(continued) 


x = stcd_i(b, Sj ) ; 

printf ( "stcd_i: Length Xd, Result 5Sd\n",x,j); 

) 

printf ( "\n " ) ; 
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stcd_l 

Synopsis 


Description 


Portability 

Returns 

Example 


Convert a decimal string to a long integer 

((include <string.h> 

length = stcd_l( in, lvalue) ; 

int length; /* input length */ 

const char *in; /* input string pointer */ 

long *lvalue; /* long integer value pointer */ 

This function scans an input string and converts the leading characters 
into long integers. The input string must begin with a plus sign (+), 
minus sign (—), or a decimal digit (0 to 9). The stcd_l function stops 
scanning the input string when it reaches the first invalid character. At 
that point, the resulting value is stored in the area addressed by the 
second argument. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

This function returns the number of input characters converted. The 
result is 0 if the first character of the input string is not a valid decimal 
digit, a plus sign (+), or a minus sign (— ). In that case, the conversion 
result pointed to by the second argument is also 0. 

((include <stdio.h> 

((include <string.h> 

void main(void) 

{ 

int x; 
long j; 
char b[80] ; 

while! 1 ) 

( 

printf ( "\nEnter a decimal value: "); 
if ( fgets(b, sizeof ( b ) ,stdin) == NULL) 

( 


break; 
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stcd_l Convert a decimal string to a long integer 
( continued ) 


x = stcd_l(b, 6j ) ; 

printf ( "stcd_l : Length ftd, Result Xld\n" , x, j ) ; 

) 

printf ( "\n" ) ; 


} 
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Stcgfe Get the filename extension 
Synopsis iinclude <string.h> 

size = stcgf e( ext, name ) ; 

int size; /* size of result string */ 

char *ext; /* extension area pointer */ 

const char *name; /* file name pointer */ 

Description This function isolates the extension portion of a filename from the path 
and node. The node is the rightmost portion of the filename that is 
separated from the rest of the name by a colon or a slash. The extension 
is the final part of the node that begins with a period, and the path is the 
leading part of the name up to the node. The following table contains 
examples of how you can isolate the parts of a filename using the 
stcgfe, stcgfn, and stcgfp functions. 


Name 
myprog . c 
/abc . dir /def 

/abc .dir/ 
def . ghi 

df 0 :yourf ile 
/abc/ 


Path 

NULL string 
abc . dir 
/abc . dir 

df 0 : 

/abc 


Node 

myprog. c 
def 

def . ghi 

yourf ile 
NULL string 


Extension 

c 

NULL string 
ghi 

NULL string 
NULL string 


The maximum number of bytes copied into your array is defined in the 
file dos . h as FESIZE. You should provide a buffer at least FESIZE 
bytes long. 

This function is not available if the _STRICT__ANSI flag has been 
defined. 

Portability SAS/C 

Returns The size value is the same as would be returned by the strlen 

function. That is, if size is 0, then the desired portion of the filename 
could not be found, and the result area contains a null string. 
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Stcgfe Get the filename extension 
(continued) 

Example § include <stdio.h> 

({include <string.h> 

{{include <dos.h> 

void main(void) 

( 

char file [ 256 ] ,path[FMSIZE] ,node[FNSIZE] ,ext[F 

while(gets(file) != NULL) 

{ 

stcgfe(ext,file) ; 
stcgfn(node, f ile) ; 
stcgfp(path, f ile) ; 
printf ("PATH: \"jfs\"\n" 

"NODE: \"$s\"\n" 

"EXT: \"J5s\"\n" , 

path, node, ext); 

) 

} 

See Also stcgfn, stcgfp, strsfn 
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Stcgfn Get a filename from a path 
Synopsis # include <string.h> 

size = stcgfn(node,name) ; 

int size; /* size of result string */ 

char *node; /* node area pointer */ 

const char *name; /* file name pointer */ 

Description This function isolates the node portion of a filename from the path and 
extension. The node is the rightmost portion of the filename that is 
separated from the rest of the name by a colon or a slash. The extension 
is the final part of the node that begins with a period, and the path is the 
leading part of the name up to the node. The following table contains 
examples of how you can isolate the parts of a filename using the 
stcgfe, stcgfn, and stcgfp functions. 


Name 

myprog . c 

/abc . dir /def 

/abc .dir/def . ghi 

df 0 :yourf ile 

/abc/ 


Path 

NULL string 
abc .dir 
/abc . dir 
df 0 : 

/abc 


Node 

myprog . c 
def 

def . ghi 
yourf ile 
NULL string 


Extension 

c 

NULL string 
ghi 

NULL string 
NULL string 


The maximum number of bytes copied into your array is defined in the 
file dos .h as FESIZE. You should provide a buffer at least FESIZE 
bytes long. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability SAS/C 

Returns The size value is the same as would be returned by the strlen 

function. That is, if size is 0, then the desired portion of the filename 
could not be found, and the result area contains a NULL string. 


See Also stcgfe, stcgfp, strsfn 
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Stcgfp Get the file path 
Synopsis # include <string.h> 

size = stcgfp (path, name) ; 

int size; /* size of result string */ 

char *path; /* path area pointer */ 

const char *name; /* file name pointer */ 

Description This function isolates the path portion of a filename from the node and 
extension. The node is the rightmost portion of the filename that is 
separated from the rest of the name by a colon, slash, or backslash. The 
extension is the final part of the node that begins with a period, and the 
path is the leading part of the name up to the node. The following table 
contains examples of how you can isolate the parts of a filename using 
the stcgf e, stcgfn, and stcgfp functions. 


Name 

myprog . c 

/abc . dir/def 

/abc . dir/def. ghi 

df 0 :yourf ile 

/abc/ 


Path 

NULL string 
abc .dir 
/abc . dir 
df 0 : 

/abc 


Node 

myprog . c 
def 

def . ghi 
your f ile 
NULL string 


Extension 

c 

NULL string 
ghi 

NULL string 
NULL string 


The maximum number of bytes copied into your array is defined in the 
file dos .h as FESIZE. You should provide a buffer at least FESIZE 
bytes long. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability SAS/C 

Returns The size value is the same as would be returned by the strlen 

function. That is, if size is 0, then the desired portion of the filename 
could not be found, and the result area contains a NULL string. 
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Stcgf p Get the file path 
( continued ) 


See Also stcgfe, stcgfn, strsfn 
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stch_i 

Synopsis 


Description 


Portability 

Returns 

Example 


Convert a hexadecimal string to an integer 

((include <string.h> 

length = stch_i( in, ivalue) ; 

int length; /* input length */ 

const char * in ; /* input string pointer */ 

int *ivalue; /* integer value pointer */ 

This function scans an unsigned string of hexadecimal digits and converts 
the leading characters into short integers. The string can contain digits 
from 0 to 9 and letters from A to F or a to f. The stch_i function stops 
scanning when it reaches the first invalid character. At that point, the 
resulting value is stored in the area addressed by the second argument. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

This function returns the number of input characters converted. The 
result is 0 if the first character of the input string is not a valid 
hexadecimal digit In that case, the conversion result pointed to by the 
second argument is 0. 

((include <stdio.h> 

((include <string.h> 

void main(void) 

( 

int x; 
int j ; 
char b [ 8 0 ] ; 

while( 1 ) 

( 

printf ( "\nEnter a hexadecimal value: "); 
if ( fgets (b, sizeof (b) , stdin) == NULL) 

{ 


break; 
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stch_i Convert a hexadecimal string to an integer 
(continued) 


x = stch_i(b, Sj ) ; 

printf ( "stch_l: Length %d, Result J5x\n",x,j) 

) 

printf ( "\n" ) ; 
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stch_l 

Synopsis 


Description 


Portability 

Returns 

Example 


Convert a hexadecimal string to a long integer 

ifinclude <string.h> 

length = stch_l (in, lvalue ) ; 

int length; /* input length */ 

const char *in; /* input string pointer */ 

long *lvalue; /* long integer value pointer */ 

This function scans an unsigned string of hexadecimal digits and converts 
the leading characters into long integers. The string can contain digits 
from 0 to 9 and letters from A to F or a to f. The stch_l function stops 
scanning the input string when it reaches the first invalid character. At 
that point, the resulting value is stored in the area addressed by the 
second argument. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

This function returns the number of input characters converted. The 
result is 0 if the first character of the input string is not a valid 
hexadecimal digit. In that case, the conversion result pointed to by the 
second argument is 0. 

Ifinclude <stdio.h> 

((include <string.h> 

void main(void) 

( 

int x; 
long j; 
char b[ 80 ] ; 

while (1) 

( 

printf ( "\nEnter a hexadecimal value: "); 
if (fgets(b,sizeof (b) ,stdin) == NULL) 

{ 


break; 
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stch_l Convert a hexadecimal string to a long integer 
(continued) 


x = stch — 1 ( b , 6 j ) ; 

printf ( "stch_l : Length %d , Result 551x\n",x,j) 

) 

printf ( "\n") ; 
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stci_d 

Synopsis 

Description 


Portability 

Returns 

Example 


Convert an integer to a decimal string 

((include <string.h> 

length = stci_d(out, ivalue) ; 

int length; /* output length */ 

char *out; /* output buffer pointer */ 

int ivalue; /* integer value */ 

This function converts an integer into an ASCII string that is the decimal 
equivalent of the integer. The output area should be at least 7 bytes long, 
which is large enough to accommodate the maximum possible string, 
including the terminating NULL byte that this function appends. 

The first output character is a minus sign if the input value is negative. 
No special leading character is generated if the value is positive. Leading 
zeroes are suppressed, and a single 0 character is generated if the input 
value is 0. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The return value is the number of characters actually placed into the 
output area, not including the final NULL byte. 

((include <stdio.h> 

Sinclude <string.h> 

void main(void) 

{ 

int i,x; 
char b[ 7] ; 

while (1) 

( 

printf ( "\nEnter an integer: "); 
if (scanf ( "Xd",6i) == EOF) 

( 


break; 
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Stci_ d Convert an integer to a decimal string 
( continued ) 

x = stci_d(b # i); 

printf ( "stci_d: Length %&, Result 5Ss\n",x,b); 

) 

printf ( "\n" ) ; 


See Also stci_h, stci_o, stcl_d, stcl_h, stcl_o, stcu_d, stcul_d 



C Library Reference 459 


stci_h 

Synopsis 

Description 

Portability 

Returns 

Example 


Convert an integer to a hexadecimal string 

jfinclude <string.h> 

length = stci_h(out, ivalue) ; 

int length; /* output length */ 

char *out; /* output buffer pointer */ 

int ivalue; /* integer value */ 

This function converts an integer into an ASCII string that is the 
hexadecimal equivalent of the integer. The output area should be at least 
5 bytes long, which is large enough to accommodate the maximum 
possible string, including the terminating NULL byte that this function 
appends. 

Leading zeroes are suppressed, and a single 0 character is generated if 
the input value is 0. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The return value is the number of characters actually placed into the 
output area, not including the final NULL byte. 

linclude <stdio.h> 
linclude <string.h> 

void main(void) 

I 

int i,x; 
char b [ 5 1 ; 

while (1) 

( 

printf ( "\nEnter an integer: "); 
if (scanf ("Sd",6i) == EOF) 

( 

break; 

} 

x = stci_h(b, i ) ; 

printf ( "stci_h: Length %d , Result fts\n",x,b); 

) 
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StCi_h Convert an integer to a hexadecimal string 
( continued ) 


printf ("\n" ) ; 

) 


See Also stci_d, stci_o, stcl_d, stcl_h, stcl_o, stcu_d, stcul_d 
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stci_o 

Synopsis 

Description 

Portability 

Returns 

Example 


Convert an integer to an octal string 

({include <string.h> 

length = stci_o(out, ivalue) ; 

int length; /* output length */ 

char *out; /* output buffer pointer */ 

int ivalue; /* integer value */ 

This function converts an integer into an ASCII string that is the octal 
equivalent of the integer. The output area should be at least 7 bytes long, 
which is large enough to accommodate the maximum possible string, 
including the terminating NULL byte that this function appends. 

Leading zeroes are suppressed, and a single 0 character is generated if 
the input value is 0. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The return value is the number of characters actually placed into the 
output area, not including the final NULL byte. 

({include <stdio.h> 

((include <string.h> 

void main(void) 

{ 

int i,x; 
char b [ 7 1 ; 

while (1) 

I 

printf ( "\nEnter an integer: "); 
if ( scanf ( "Xd" , Si ) == EOF) 

{ 

break; 

} 

x = stci_o(b, i ) ; 

printf ( "stci_o: Length %d , Result ?5s\n",x,b); 

i 


printf ( "\n" ) ; 
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Stci_© Convert an integer to an octal string 
(continued) 


See Also stci_d, stci_h, stcl_d, stcl_h, stcl_o, stcu_d, stcul_d 
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stcis 

Synopsis 


Description 


Portability 

Returns 

Example 


Count the number of string characters in the set 
((include <string.h> 
length = stcis(s,b) ; 

int length; /* span length in bytes */ 

const char *s; /* points to string being scanned */ 

const char *b; /* points to character set string */ 

This function counts the number of characters at the beginning of the 
string s that are included in the character set specified by the argument 
b. For example, if string s is hello, and set b includes the characters 
h, e, and 1, the stcis function returns a 4. The stcis function is 
provided for compatibility with previous versions of the compiler. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

This function returns the number of bytes that are in the specified 
character set. The scan always stops when the NULL terminator byte is 
reached. 

((include <stdio.h> 

((include <string.h> 

void main(void) 

( 

char si [256] ,s2[256] ; 

while( 1 ) 

( 

printf ( "\nEnter test string: "); 

if ( fgets ( s 1 , sizeof ( s 1 ) , stdin) == NULL) 

( 

break; 

} 

printf ( "Enter span string: "); 

if ( fgets ( s2 , sizeof ( s2 ), stdin) == NULL) 

( 

break; 

) 

printf ( "stcis: Sd\n" , stcis (s 1 , s2) ) ; 
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StciS Count the number of string characters in the set 
(continued) 


) 

printf ( "\n" ) ; 


See Also stcisn, strspn 
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stcisn 

Synopsis 


Description 


Portability 

Returns 

Example 


Count the number of string characters not in the set 
((include <string.h> 
length = stcisn(s f b); 

int length; /* span length in bytes */ 

const char *s; /* points to string being scanned */ 

const char *b; /* points to character set string */ 

This function counts the number of characters at the beginning of the 
string s that are not included in the character set specified by the 
argument b. For example, if string s is hello, and set b includes the 
characters h, e, and 1, the stcisn function returns a 0. The stcisn 
function is provided for compatibility with previous versions of the 
compiler. 

This function is not available if the _strict_ansi flag has been 
defined. 

SAS/C 

This function returns the number of bytes that are not in the specified 
character set. The scan always stops when the NULL terminator byte is 
reached. 

((include <stdio.h> 

((include <string.h> 

void main(void) 

{ 

char si [256] ,s2[256] ; 
while( 1 ) 

I 

printf ( "\nEnter test string: "); 
if (fgets(s1 ,sizeof (si ) ,stdin) == NULL) 

{ 


break; 
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stcisn Count the number of string characters not in the set 
(continued) 

printf ( "Enter span string: "); 
if (fgets(s2,sizeof (s2) ,stdin) == NULL) 
( 

break; 

} 

printf ( "stcisn: Xd\n" , stcisn(s1 ,s2) ) ; 

} 

printf ( "\n" ) ; 


See Also stcis, strcspn 



C Library Reference 467 


stcl_d Convert a long integer to a decimal string 
Synopsis (f include <string.h> 


length = stcl_d( out, lvalue ) ; 


int length; 
char *out; 
long lvalue; 


/* output length */ 

/* output buffer pointer */ 
/* long integer value */ 


Description This function converts a long integer into an ASCII string that is the 

decimal equivalent of the integer. The output area should be at least 13 
bytes long, which is large enough to accommodate the maximum possible 
string, including the terminating NULL byte that this function appends. 

The first output character is a minus sign if the input value is negative. 
No special leading character is generated if the value is positive. Leading 
zeroes are suppressed, and a single 0 character is generated if the input 
value is 0. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


Portability SAS/C 

Returns The return value is the number of characters actually placed into the 
output area, not including the final NULL byte. 

Example # include <stdio.h> 

((include <string.h> 


void main(void) 

I 

int x; 
long 1; 
char b[ 13] ; 


while (1) 


printf ( "\nEnter an integer: "); 
if ( scanf ( "$ld" , 61) == EOF) 

{ 

break; 

i 
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stcld Convert a long integer to a decimal string 
(continued) 

x = stcl d ( b r 1 ) ; 

printf ("stcl_d: Length jSd, Result 5Ss\n",x,b); 

) 

printf ( "\n" ) ; 


See Also stci_d, stci_h, stci_o, stcl_h, stcl_o, stcu_d, stcul_d 
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stcl_h 

Synopsis 

Description 

Portability 

Returns 

Example 


Convert a long integer to a hexadecimal string 

((include <string.h> 

length = stcl_h( out, lvalue) ; 

int length; /* output length */ 

char *out; /* output buffer pointer */ 

long lvalue; /* long integer value */ 

This function converts a long integer into an ASCII string that is the 
hexadecimal equivalent of the integer. The output area should be at least 
9 bytes long, which is large enough to accommodate the maximum 
possible string, including the terminating NULL byte that each function 
appends. 

Leading zeroes are suppressed, and a single 0 character is generated if 
the input value is 0. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The return value is the number of characters actually placed into the 
output area, not including the final NULL byte. 

((include <stdio.h> 

((include <string.h> 

void main(void) 

( 

int x; 
long 1; 
char b[ 9 ] ; 

while (1) 

{ 

printf ( "\nEnter an integer: "); 
if (scanf ("Kid", 61) == EOF) 

I 

break; 

) 

x = stcl_h(b, 1 ) ; 
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stcl_h Convert a long integer to a hexadecimal string 
(continued) 

printf ( "stcl_h: Length ftd, Result 55s\n",x f b) ; 

) 

printf ( "\n" ) ; 


See Also stci_d, stci_h, stci_o, stcl_d, stcl_o, stcu_d, stcul_d 
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stcl_o 

Synopsis 

Description 

Portability 

Returns 

Example 


Convert a long integer to an octal string 

((include <string.h> 

length = stcl_o( out , lvalue ) ; 

int length; /* output length */ 

char *out; /* output buffer pointer */ 

long lvalue; /* long integer value */ 

This function converts a long integer into an ASCII string that is the octal 
equivalent of the integer. The length of the output area should be at least 
12 bytes long, which is large enough to accommodate the maximum 
possible string, including the terminating NULL byte that this function 
appends. 

Leading zeroes are suppressed, and a single 0 character is generated if 
the input value is 0. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The return value is the number of characters actually placed into the 
output area, not including the final NULL byte. 

(linclude <stdio.h> 

^include <string.h> 

void main(void) 

{ 

int x; 
long 1; 
char b( 13 1 ; 

while (1) 

( 

printf ( "\nEnter an integer: "); 
if (scanf ("Kid", 61) == EOF) 

{ 

break; 

) 

x = stcl_o(b,l); 
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stclo Convert a long integer to an octal string 
( continued ) 


printf ( "stcl_o: Length Kd, Result Jts\n",x,b); 

) 

printf ("\n ") ; 


See Also stci_d, stci_h, stci_o, stcl_d, stcl_h, stcu_d, stcul_d 
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Stolen Measure the length of a string 
Synopsis § include <string.h> 
length = stclen(s); 

size_t length; /* number of bytes in s (before null) */ 
const char *s; 


Description This function, which is equivalent to the ANSI Standard function 

strlen, returns the number of bytes in the string s before the null 
terminator byte. 

This function is implemented as a macro and is provided only for 
compatibility with previous releases. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability OLD 

Returns The length equals the number of bytes in the string before the NULL byte. 

See Also strlen 
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stco_i 

Synopsis 


Description 


Portability 

Returns 

Example 


Convert an octal string to an integer 

((include <string.h> 

length = stco_i(in,ivalue) ; 

int length; /* input length */ 

const char *in; /* input string pointer */ 

int *ivalue; /* integer value pointer */ 

This function scans an unsigned octal string and converts the leading 
characters into short integers. The string can consist of octal digits 0 to 7. 
The stco_i function stops scanning the input string when it reaches the 
first invalid character. At that point, the resulting value is stored in the 
area addressed by the second argument. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

This function returns the number of input characters converted. The 
result is 0 if the first character of the input string is not a valid octal 
digit. In that case, the conversion result pointed to by the second 
argument is 0. 

((include <stdio.h> 

((include <string.h> 

void main(void) 

( 

int x; 
int j ; 
char b( 80 ] ; 

while( 1 ) 

{ 

printf ( "\nEnter an octal value: "); 
if ( fgets (b, sizeof (b) , stdin) == NULL) 

( 

break; 

} 

x = stco_i(b, Sj ) ; 



C Library Reference 475 


StCO_i Convert an octal string to an integer 
(continued) 

printf ( "stco_i: Length %d , Result JSx\n",x,j); 

} 

printf ( "\n " ) ; 

} 

See Also stcd_i, stcd_l, stch_i, stch_l, stco_l 
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stco_l 

Synopsis 


Description 


Portability 

Returns 

Example 


Convert an octal string to a long integer 

((include <string.h> 

length = stco_l (in, lvalue ) ; 

int length; /* input length */ 

const char *in; /* input string pointer */ 

long *lvalue; /* long integer value pointer */ 

This function scans an unsigned octal string and converts the leading 
characters into long integers. The string can consist of octal digits 0 to 7. 
The s tco — 1 function stops scanning the input string when it reaches the 
first invalid character. At that point, the resulting value is stored in the 
area addressed by the second argument. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

This function returns the number of input characters converted. The 
result is 0 if the first character of the input string is not a valid octal 
digit. In that case, the conversion result pointed to by the second 
argument is 0. 

^include <stdio.h> 

Sinclude <string.h> 

void main(void) 

{ 

int x; 
long j ; 
char b [ 8 0 ] ; 

while( 1 ) 

( 

printf ( "\nEnter an octal value: "); 
if (fgets(b,sizeof (b) ,stdin) == NULL) 

( 

break; 

) 


X = stco_l(b, 6 j ) ; 
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StCO_ I Convert an octal string to a long integer 
( continued ) 

printf ( "stco_l: Length Xd, Result 5Slx\n" f x, j) ; 

) 

printf ( "\n" ) ; 

) 

See Also stcd_i, stcd_l, stch_i, stch_l, stco_i 
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Stcpm Unanchored pattern match 
Synopsis f include <string.h> 


size = stcpm(string, pattern, match) ; 


int size; 

const char *string; 
const char *pattern; 
char **match; 


/* size of matching string */ 

/* string to be scanned */ 

/* pattern string */ 

/* returns pointer to matching string */ 


Description This function scans a string to find a specified pattern. You can use the 
following wildcard characters to specify a pattern: 


Pattern 

Matches 

? 

any single character 

c* 

zero or more occurrences of character c 

c+ 

one or more occurrences of character c 

\? 

a question mark (?) 

V 

an asterisk (*) 

\+ 

a plus sign (+) 


Any other character must match exactly. The following table lists some 
examples. 

Pattern Matches 

abc only abc 

ab*c ac, abc, or abbc 

ab+c abc, abbc, or abbbc 

ab?*c a string starting with ab and ending in c, for example, 
abxyzc 

only ab*c 


ab\*c 
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Stcpm Unanchored pattern match 
(continued) 


The match can occur anywhere in the string. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability SAS/C 

Returns The function returns the size of the matching string or 0 if there was no 
match. It also returns a pointer to the beginning of the matching string in 
the parameter match. 

Example f include <stdio.h> 

Sinclude <stdlib.h> 
iinclude <string.h> 

void main(void) 

{ 

char s[ 100] ,p[ 100] ,*r; 
int x; 

while( 1 ) 

{ 

printf ( "\nSearch string => "); 
if (gets(s) == NULL) 

{ 

break; 

) 

printf ( "Pattern => "); 

if (gets(p) == NULL) 

( 

break; 

} 


x = stcpm(s,p,Sr) ; 
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Stcpm Unanchored pattern match 
(continued) 

if (x) 

{ 

printf( "stcpm: size = 55 d, " 
"match = \"55 . *s\"\n" , 
x , x , r ) ; 

) 

else 

( 

printf( "stcpm: nomatch\n"); 
exit (EXIT-FAILURE) ; 

} 

) 

printf ( "\n") ; 


See Also astcsma, stcpma, stcsma 
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stcpma 

Synopsis 


Description 


Anchored pattern match 

((include <string.h> 

size = stcpma(string,pattern) ; 

int size; /* size of matching string */ 

const char *string; /* string to be scanned */ 

const char ^pattern; /* pattern string */ 

This function scans a string to find a specified pattern. You can use the 
following wildcard characters to specify a pattern: 


Pattern 

Matches 

? 

any single character 

c* 

zero or more occurrences of character c 

c+ 

one or more occurrences of character c 

\? 

a question mark (?) 

V 

an asterisk (*) 

\+ 

a plus sign (+) 


Any other character must match exactly. Some examples are: 


Pattern Matches 

abc only abc 

ab*c ac, abc, or abbc 

ab+c abc, abbc, or abbbc 

ab?*c a string starting with ab and ending in c, for example, 
abxyzc 

ab\*c only ab*c 


The match must occur at the beginning of the string. 
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Stcpma Anchored pattern match 
(continued) 


This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability SAS/C 

Returns The function returns the size of the matching string or 0 if there was no 
match. 

Example i include <stdio.h> 

({include <string.h> 

void raain(void) 

{ 

char s [ 100] f p[ 100] ; 
int x; 

while( 1 ) 

{ 

printf ("\nSearch string => "); 
if (gets(s) == NULL) 

{ 

break; 

} 

printf ( "Pattern => "); 

if (gets(p) == NULL) 

{ 

break; 

} 


x = stcpma(s,p); 
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StCpma Anchored pattern match 
(continued) 

if (x) 

( 

printf ( "stcpma: size = %d f " 
"match = \"?S.*s\"\n" , 
x, x, s); 


else 

( 

printf ( "stcpma: nomatch\n"): 

} 

) 

printf ( "\n" ) ; 


See Also astcsma, stcpm, stcsma 
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stcsma 

Synopsis 


UNIX string pattern match (anchored) 
jlinclude <string.h> 
length = stcsma (s,p); 


int length; 
const char *s; 
const char *p; 


/* length of matching string */ 
/* string being scanned */ 

/* pattern string */ 


Description The function stcsma performs an anchored pattern match of the type 
used by the UNIX shell. The only meta-characters recognized are the 
asterisk (*) and the question mark (?). The asterisk matches an arbitrary 
number of characters, and the question mark matches exactly one 
character. The pattern must match at the beginning of the supplied string. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


Portability AmigaDOS 

Returns This function returns the length of the matching string or 0 if there was 
no match. 

See Also astcsma, stcpm, stcpma 
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stcud 

Synopsis 

Description 

Portability 

Returns 

Example 


Convert an unsigned integer to a decimal string 

((include <string.h> 

length = stcu_d(out,uivalue) ; 

int length; /* output length */ 

char *out; /* output buffer pointer */ 

unsigned uivalue; /* unsigned value */ 

This function converts an unsigned integer into an ASCII string that is 
the decimal equivalent of the integer. The length of the output area 
should be at least 6 bytes long, which is large enough to accommodate 
the maximum possible string, including the terminating NULL byte that 
this function appends. 

Leading zeroes are suppressed, and a single 0 character is generated if 
the input value is 0. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The return value is the number of characters actually placed into the 
output area, not including the final null byte. 

((include <stdio.h> 

((include <string.h> 

void main(void) 

( 

unsigned int i; 
int x; 
char b [ 13] ; 

while( 1 ) 

{ 

printf ( "\nEnter an integer: "); 
if ( scanf ( "Xu" , 6i ) == EOF) 

{ 

break; 

} 


x = stcu_d(b,i); 
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StCU_d Convert an unsigned integer to a decimal string 
(continued) 


printf ("stcu_d: Length %d, Result JEs\n",x,b); 

} 

printf ( "\n" ) ; 


See Also stci_d, stci_h, stci_o, stcl_d, stcl_h, stcl_o, stcul_d 
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stcul_d 

Synopsis 

Description 

Portability 

Returns 

Example 


Convert an unsigned long integer to a decimal string 

((include <string.h> 

length = stcul_d(out,ulvalue) ; 

int length; /* output length */ 

char *out; /* output buffer pointer */ 

unsigned long ulvalue; /* unsigned long integer value */ 

This function converts an unsigned long integer into an ASCII string that 
is the decimal equivalent of the integer. The output area should be at 
least 12 bytes long, which is large enough to accommodate the maximum 
possible string, including the terminating NULL byte that each function 
appends. 

Leading zeroes are suppressed, and a single 0 character is generated if 
the input value is 0. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The return value is the number of characters actually placed into the 
output area, not including the final NULL byte. 

((include <stdio.h> 

((include <string.h> 

void main(void) 

1 

int x; 

unsigned long i; 
char b[ 12] ; 

while( 1 ) 

( 

printf ( "\nEnter an integer: "); 
if (scanf ( "Xlu",fii) == EOF) 

( 

break; 

) 

x = stcul_d(b, i) ; 
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StCUl_d Convert an unsigned long integer to a decimal string 
(continued) 


printf ( "stcul_d: Length Xd, Result Ss\n",x,b) 

) 

printf ( "\n" ) ; 


See Also stci_d, stci_h, stci_o, stcl_d, stcl_h, stcl_o 
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stpblk Skip blanks 
Synopsis # include <string.h> 
q = stpblk(p); 

char *q; /* updated string pointer */ 

const char *p; /* string pointer */ 

Description This function advances the string pointer past blank characters, that is, 
past all the characters for which the is space function is true. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


Portability SAS/C 

Returns The function returns a pointer to the next nonblank character. The NULL 
terminator byte is not considered a blank, and so the function will not go 
past the end of the string. 

Example | include <stdio.h> 

Kinclude <string.h> 


void raain(void) 

( 

char input[256] ; 


while( 1 ) 

{ 

puts( "\nEnter a string with leading blanks..."); 
if (gets(input) == NULL) 

( 

break; 

) 

printf ( "*s\n" ,stpblk( input) ) ; 

} 

printf ( "\n" ) ; 


See Also stcis, strspn 
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stpbrk Find a break character in a string 
Synopsis # include <string.h> 
p = stpbrk(s,b) ; 

char *p ; /* points to break character in s */ 

const char *s; /* string to be scanned */ 

const char *b; /* break characters */ 

Description This function scans string s to find the first occurrence of a character 
from break string b. 

This function is provided for compatibility with previous releases of the 
compiler. The ANSI function strpbrk is equivalent to the stpbrk 
function. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability OLD 

Returns If no character from string b is found in string s, a NULL pointer is 
returned. Otherwise, p is a pointer to the first break character. 

See Also strcspn, strpbrk, strspn 
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stpchr 

Synopsis 


Description 


Portability 

Returns 


Find a character in a string 
jfinclude <string.h> 
p = stpchr ( s ,c) ; 

char *p; /* updated string pointer */ 

const char *s; /* input string pointer */ 

int c; /* character to be located */ 

The stpchr function scans the input string to find the first occurrence 
of the character specified by argument c. The stpchr function is 
provided for compatibility with previous releases of the compiler. The 
ANSI function strchr is equivalent to the stpchr function. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

OLD 

The stpchr function returns a NULL pointer if the input string is empty 
or if the specified character is not found. 


See Also stpchrn, strchr, strrchr 
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stpchrn 

Synopsis 


Description 


Portability 

Returns 


Find a character not in a string 
({include <string.h> 
p = stpchrn(s,c ) ; 

char *p ; /* updated string pointer */ 

const char *s; /* input string pointer */ 

int c; /* character to be located */ 

The stpchrn function scans the input string for the first occurrence of 
some character other than that specified in the c argument. This function 
is provided for compatibility with previous releases of the compiler. The 
ANSI function strrchr is equivalent to the stpchrn function. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

OLD 

The stpchrn function returns a NULL pointer if the input string is 
empty or consists entirely of character c. 


See Also stpchr, strchr, strrchr 
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stpcpy 

Synopsis 


Description 

Portability 

Returns 

Example 


Copy one string to another 
((include <string.h> 
np = stpcpy ( to, from) ; 

char *np; /* points to end of destination string */ 

char *to; /* destination pointer */ 

const char *from; /* source pointer */ 

This function copies the NULL-terminated source string to the destination 
area. The entire source string is copied, and the resulting destination is 
always NULL-terminated. 

This function is not available if the _STRICT__ANSI flag has been 
defined. 

SAS/C 

The stpcpy function returns a pointer to the end of the destination 
string, which is useful when you are building a string from several 
pieces. 

Note: The ANSI strcpy function returns the to string, but this 
function returns a pointer to the NULL byte after the to string. 

/* 

* This example should print: Hello, my name is Flo. 

*/ 

((include <stdio.h> 

((include <string.h> 

void main(void) 

( 

char b[ 256 ] , *p; 

p = stpcpy (b, "Hello, "); 
p = stpcpy(p,"my name is " ) ; 
p = stpcpy(p, "Flo . " ) ; 
puts(b) ; 

} 


See Also stccpy, strcpy, strncpy 
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Stpdate Convert a date array to a string 
Synopsis tfinclude <string.h> 

np = stpdate(p, mode, date) ; 

char *np; /* updated output string pointer */ 


char *p ; /* output string pointer */ 

int mode; /* conversion mode */ 

const char *date; /* date array, as follows */ 

/* date[0] => year - 1980 */ 

/* date [ 1 ] => month (1 to 12) */ 

/* date[2] => day (1 to 31) */ 


Description This function converts a 3-byte date array into ASCII or BCD according 
to the mode argument: 


Mode 

Format 

Type 

Length 

0 

yymmdd 

BCD 

3 bytes 

1 

yymmdd 

ASCII 

7 bytes 

2 

mm/dd/yy 

ASCII 

9 bytes 

3 

mm-dd-yy 

ASCII 

9 bytes 

4 

mmm d yyyy 

ASCII 

up to 13 bytes 

5 

Mm . . . m d , yyyy 

ASCII 

up to 19 bytes 

6 

dd MMM yy 

ASCII 

10 bytes 

7 

dd MMM yyyy 

ASCII 

12 bytes 


In the above formats, MMM represents a 3-character month abbreviation 
in capitals, and Mm . . . m represents the full month name (for example, 
January). The mm, dd, and yy terms are 2-character month, day, and 
year, respectively, while d is the date with the leading zero suppressed. 
The yyyy term is the 4-character year obtained by adding 1980 to the 
first byte of the date array. 

For all modes except 0, a NULL byte is appended to the output string. 

This function is not available if the _STRICT_ansi flag has been 
defined. 
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stpdate Convert a date array to a string 
(continued) 

Portability SAS/C 

Returns The function does not make validity checks on the date array. It returns a 
pointer to the first byte past the generated output. For modes other than 
0, this is a pointer to the NULL terminator byte. 


See Also getclk, getft, stptime 



496 Chapter 7 


stpsym 

Synopsis 


Description 


Portability 

Returns 

Example 


Get the next symbol from a string 
ifinclude <string.h> 
p = stpsym(s,sym, symlen) ; 


char *p ; 
const char *s; 
char *sym; 
int symlen; 


/* points to next input character */ 
/* input string */ 

/* output string */ 

/* sizeof(sym) */ 


This function breaks out the next symbol from the input string. The first 
character of the symbol must be alphabetic (upper- or lowercase), and the 
remaining characters must be alphanumeric. The pointer is not advanced 
past any initial white space in the input string. 

The output string is the NULL-terminated symbol and will be an empty 
string if no symbol is found. If the symbol is longer than symlen- 1, its 
excess characters are dropped. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The function returns a pointer to the next character past the symbol. 

tfinclude <stdio.h> 
iinclude <string.h> 

void main(void) 

{ 

char a [ 256 ] , b [ 1 0 ] ; 
char *p; 

while ( 1 ) 

{ 

printf ( "\nEnter text string: "); 

if (gets(a) == NULL) 


break; 

) 


p = a; 
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stpsym Get the next symbol from a string 
( continued ) 

while( 1 ) 

{ 

p = stpsym(p,b,sizeof (b) ) ; 
printf( "Symbol: \"55s\"\n" 

"Residual: \"JSs\"\n\n", 

b, p); 

if (b[ 0 ] == • \0 ' ) 

{ 

break; 

} 

p++; 

} 

) 

printf ( "\n" ) ; 


See Also stcarg, stpbrk, strcspn, strpbrk 
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stptime 

Synopsis 


Description 


Convert a time array to a string 

jfinclude <string.h> 

np = stptime (p,mode, time ) ; 


char *np; 
char *p; 
int mode; 
const char *time; 


/* updated output string pointer */ 

/* output string pointer */ 

/* conversion mode */ 

/* time array, as follows */ 

/* time[0] => hour (0 to 23) */ 

/* t ime [ 1 ] => minute (0 to 59) */ 

/* time[2] => second (0 to 59) */ 

/* time(3] => hundredths (0 to 99) */ 


This function converts a 4-byte time array into ASCII or BCD according 
to the mode argument: 


Mode 

Format 

Type 

Length 

0 

hhmmssdd 

BCD 

4 bytes 

1 

hhmmss 

ASCII 

7 bytes 

2 

hh :mm: ss 

ASCII 

9 bytes 

3 

hhmmssdd 

ASCII 

9 bytes 

4 

hh :mm: ss . dd 

ASCII 

12 bytes 

5 

hh :mm 

ASCII 

6 bytes 

6 

hr:mm:ss HH 

ASCII 

12 bytes 

7 

hr: mm HH 

ASCII 

9 bytes 


The hh, mm, ss, and dd terms are the 2-digit (BCD or ASCII) 
equivalents of the binary values in the time array. The hr term is the 
2-digit hour using the 12-hour form, and the HH term is either AM or 
PM. 

A NULL terminator byte is appended to the ASCII output strings. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


Portability SAS/C 
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Stptime Convert a time array to a string 
(continued) 

Returns The function does not make validity checks on the time array. It returns a 
pointer to the first byte past the generated output. For modes other than 
0, this is a pointer to the NULL terminator byte. 


See Also getclk, getft, stpdate 
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stptok 

Synopsis 


Description 


Portability 

Returns 

Example 


Get the next token from a string 
((include <string.h> 


p = stptok(s,tok,toklen,brk ) ; 


char *p; 

/* 

points 

const char *s; 

/* 

points 

char *tok; 

/* 

points 

int toklen; 

/* 

size o: 

const char *brk: 

/* 

break : 


to next character after token */ 
to input string */ 
to output buffer */ 

: buffer pointed to by tok */ 
:tring */ 


This function breaks out the next token from the input string and moves 
it to the token buffer with a null terminator. A token consists of all 
characters in the input string s up to but not including the first character 
that is in the break string. In other words, the brk argument specifies 
the characters that cannot be included in a token. If the input string 
begins with a break character, then the token buffer will contain a null 
string, and the return pointer p will be the same as the argument s . If 
no break character is found after toklen-1 input characters have been 
moved to the token buffer, or if the input string terminator (a NULL byte) 
is reached, then the scan stops as if a break character were reached. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


SAS/C 

The function returns a pointer to the next character in the input string. 
/* 

* This example breaks out words that are 

* separated by blanks or commas. 

* The token buffer takes on the following 

* values as the program loops: 

* 

* LOOP TOKEN 

* 1 first 

* 2 second 

* 3 third 

* 4 fourth 
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stptok Get the next token from a string 
(continued) 


jfinclude <stdio.h> 

((include <string.h> 

char test[] = "first, second third, fourth"; 

void main(void) 

( 

char *p = test; 
char token[ 50 1 ; 

while( 1 ) 

( 

p = stptok(p, token, sizeof (token) , " ,"); 
printf ( "$s\n" , token) ; 
if ( *p == ' \0 ' ) 

( 

break; 

} 

p = stpblk(++p); 


) 


See Also stpblk, strtok 
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strbpl 

Synopsis 


Description 


Portability 

Returns 

Example 


Build a string pointer list 
((include <string.h> 
n = strbpl(s,max,t) ; 

int n; /* number of pointers */ 

char *s[]; /* pointer to string pointer list */ 

int max; /* maximum number of pointers */ 

const char *t; /* text pointer */ 

This function constructs a list of pointers to the strings contained within 
the specified text array. Each string must be NULL-terminated, and the 
text array must be terminated by a NULL string. In other words, array t 
must end with two NULL bytes, one to terminate the final string and 
another to terminate the array. The string pointer list s is terminated by 
a NULL pointer. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The return value indicates how many string pointers were placed into 
array s. If the number of strings plus the final NULL pointer is greater 
than the argument max, a value of —1 is returned. 

((include <stdio.h> 

^include <string.h> 

char text [ ] = ("string 1", "string 2",'\0'); 

void main(void) 

( 


char *list[5] ; 
int count, i; 
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strbpl Build a string pointer list 
( continued ) 


/* 

* The following call has the following effect: 

* 

* Return value (count) is 2. 

* list [ 0 ] => "string 1" 

* list[ 1 ] => "string 2" 

* list [ 2 ) => NULL 

*/ 

count = strbpl(list,5,text) ; 

printf("Jtd strings were found: \n", count); 

for (i=0; i<count; i++) 

{ 

printf ("*s\n", list [ i ] ) ; 

) 


See Also getfnl, strsrt 
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Strcat Concatenate strings 
Synopsis # include <string.h> 
p = strcat(to,from) ; 


char *p; 

char *to; 

const char *from; 


/* same as destination string pointer */ 
/* destination string pointer */ 

/* source string pointer */ 


Description This function concatenates the source string to the end of the destination 
string, overwriting the existing NULL byte at the end of the destination 
string. The strcat function places a NULL byte at the new end of the 
destination string. 


Portability ANSI 

Returns This function returns a pointer that is the same as the first argument. 

Example jf include <stdio.h> 

((include <string.h> 


char first[ 100] ; 
char *second=" a test"; 


void main(void) 

{ 

strcpy( first, "This is"); 
strcat(first, second); 
printf ( "Xs\n" , first); 

/* output is "This is a test" */ 

} 


See Also stpcpy, strncat 
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strchr 

Synopsis 

Description 

Portability 

Returns 

Example 


Find a character in a string 
((include <string.h> 
p = strchr(s,c) ; 

char *p; /* updated string pointer */ 

const char *s; /* input string pointer */ 

int c; /* character to be located */ 

The strchr function scans the input string to find the first occurrence 
of the character specified by the argument c. 

ANSI 

A NULL pointer is returned if the input string is empty or if the specified 
character is not found. Otherwise, this function returns a pointer to the 
first matching character in the argument s . 

((include <stdio.h> 

((include <string.h> 

void main(void) 

( 

char *p; 

p=strchr( "This is a test",'t'); 

/* p now points to "test" */ 
printf("Xs\n",p); 

p=strchr( "This is a test", 's'); 

/* p now points to "s is a test" */ 
printf ( ")Ss\n",p) ; 


See Also stpchrn, strchr, strrchr 
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strcmp 

Synopsis 


Description 


Portability 

Returns 


Compare strings, case sensitive 
^include <string.h> 
x = strcmp(a,b); 

int x; /* comparison result */ 

const char *a,*b; /* strings being compared */ 

This function compares two NULL-terminated strings. The ASCII collating 
sequence is used in all cases. 

The relative collating sequence of the strings is indicated by the sign of 
the return value, as follows: 


Sign 

Meaning 

negative 

first string is below the second 

zero 

strings are equal 

positive 

first string is above the second 


If the strings have different lengths, the shorter one is treated as if it 
were extended with zeroes. The strcmp function has a built-in version 
that is equivalent to the standard library version. The statement 
#include <string.h> provides a default setting by which built-in 
functions are accessed. If you do not want the built-in function, you can 
enter an #undef strcmp after including the string.h file. 

ANSI 

The sign of the return value indicates the relative collating sequence of 
the strings, as indicated above. 
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Strcmp Compare strings, case sensitive 
(continued) 

Example | include <stdio.h> 

((include <string.h> 

void result(char *name, int r) 

{ 

char *p; 

if (r == 0) 

{ 

p = "is equal to"; 

) 

if (r < 0) 

{ 

p = "is less than"; 

) 

if (r > 0) 

( 

p = "is greater than"; 

) 

printf("Ss string A 55s string B\n" ,name,p) ; 
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Strcmp Compare strings, case sensitive 
(continued) 

void main(void) 

( 

char a [ 256 ] ,b[256] ; 

while( 1 ) 

{ 

printf ( "Enter string A: "); 
if (fgets(a,sizeof (a) ,stdin) == NULL) 
{ 

break; 

} 

printf { "Enter string B: "); 
if (fgets(b,sizeof (b) ,stdin) == NULL) 
{ 

break; 

) 

result! "strcmp: " , strcmp(a,b) ) ; 

) 

printf ("\n"); 


See Also s 


trcmpi, stricmp, strncmp, strnicmp 
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strcmpi 

Synopsis 


Description 


Portability 

Returns 


Compare strings, case insensitive 
((include <string.h> 
x = strcmpi ( a, b) ; 

int x; /* comparison result */ 

const char *a,*b; /* strings being compared */ 

This function compares two NULL-terminated strings using the ASCII 
collating sequence. The strcmpi function does not distinguish between 
uppercase and lowercase. This function is a hold-over from various 
Microsoft compilers. Use the stricmp function in new code. 

The relative collating sequence of the strings is indicated by the sign of 
the return value, as follows: 


Return Meaning 

negative first string is below the second 

zero strings are equal 

positive first string is above the second 


If the strings have different lengths, the shorter one is treated as if it 
were extended with zeroes. 

This function is not available if the _STRICT_ansi flag has been 
defined. 

OLD 

The sign of the return value indicates the relative collating sequence of 
the strings, as indicated above. 


See Also strcmp, stricmp, strncmp, strnicmp 
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strcoll 

Synopsis 


Description 

Portability 

Returns 

Example 
See Also 


Compare strings based on locale 
finclude <string.h> 
res = strcoll(s1 , s2) ; 

int res; /* result of comparison */ 

const char *s1,*s2; /* strings to compare */ 

This function compares two strings based on the current locale. Because 
of the limitations of the ANSI specifications, this function cannot correctly 
handle the rules of the German collating sequence completely. 

ANSI 

This function returns a 0 if both strings are equal. If string s 1 is logically 
less than string s 2, the return value is less than 0. If string s 1 is 
logically greater than string s2, the return value is greater than 0. 

if ( !strcoll( "stringl" , "string2")) 

printf("This is funny, they shouldn't match\n"); 

setlocale 
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strcpy 

Synopsis 


Description 


Portability 

Returns 


Copy one string to another 
((include <string.h> 
p = strcpy(to, from) ; 

char *p; /* same as destination pointer */ 

char *to ; /* destination pointer */ 

const char *from; /* source pointer */ 

This function copies the entire NULL-terminated source string to the 
destination area. The resulting destination is always NULL-terminated. 

The strcpy function has a built-in version that is equivalent to the 
standard library version. The statement ((include <string.h> 
provides a default setting by which built-in functions are accessed. If you 
do not want the built-in function, you can use an #undef strcpy 
statement after including the file str ing . h. 

ANSI 

This function returns a pointer that is the same as the destination 
pointer. 


See Also stccpy, stpcpy, strncpy 
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strcspn 

Synopsis 


Description 

Portability 

Returns 

Example 


Count the number of string characters not in the set 
iinclude <string.h> 
length = strcspn( s ,b) ; 

size_t length; /* span length in bytes */ 

const char *s; /* points to string being scanned */ 

const char *b; /* points to character set string */ 

This function measures the number of characters at the beginning of 
input string s that are not in the character set specified by the argument 
b. 

ANSI 

This function returns the number of bytes that are not in the specified 
character set. The scan always stops when the null terminator byte is 
reached. 

{(include <stdio.h> 

((include <string.h> 

char *test = "This is a test"; 

void checkspan(char *string, char *set) 

( 

printf ("String: XsNnScan Set: Xs\n" 

"strcspn: ftd\n" , string, set, 

strcspn( string, set)); 

} 

void main(void) 

{ 

checkspan( test, "xyz" ) ; 
checkspan(test, "s" ) ; 
checkspan(test, "TXI" ) ; 

1 


See Also 


stcis, stcisn, strspn 
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strdup 

Synopsis 


Description 

Portability 

Returns 


Duplicate a string 
Hinclude <string.h> 
p = strdup(s) ; 

char *p ; /* points to duplicate string */ 

const char *s; /* points to string being duplicated */ 

This function creates a duplicate of the specified string by using the 
malloc and strcpy functions to allocate space and copy the string to 
it. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

XENIX 

A NULL pointer is returned if the malloc functions fails. Otherwise, the 
function returns a pointer to the duplicate string. 


See Also malloc, strcpy 
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strerror 

Synopsis 

Description 

Portability 

Returns 

Example 


Print the text for a given error number 
((include <string.h> 
p = strerror (error ) ; 

char *p; /* Pointer to text string */ 

int error; /* Error number */ 

This function takes a specified error number and returns a pointer to a 
text string that describes the error. 

ANSI 

This function returns a pointer to the text of the corresponding error 
message. If it could not find the error, it returns a NULL pointer. The 
string is valid until the next call to the strerror function and must not 
be modified by the caller. 

/* 

* Print out an error from unlinking a file 
*/ 

((include <stdio.h> 

((include <stdlib.h> 

((include <string.h> 

extern long errno; 

void main(void) 

i 

unlink( "xyzzy: lambda" ) ; 
if (errno) 

( 

printf ( "Error removing file: Xs\n", 
strerror (errno) ) ; 
exit (EXIT-FAILURE) ; 

} 


See Also 


errno 
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strftime Format a time string 

Synopsis # include <time.h> 

ret = strftime(s, maxsize, format, timeptr); 

size_t ret; /* number of characters in */ 

/* formatted string */ 

char *s; /* string to place characters in */ 

size_t maxsize; /* maximum string size */ 

const char *format; /* format instructions for string */ 

const struct tm *timeptr; /* broken-down time information */ 

Description This function is similar to the sprintf function but has its own 
formatting instructions for printing out time information. 

This function places characters into the array pointed to by the 
argument s in the format specified by the string pointed to by the 
argument format. The format argument consists of zero or more 
conversion specifiers and ordinary characters. All ordinary characters, 
including the terminating NULL character, are copied unchanged into the 
array, but the conversion specifiers are replaced by the appropriate 
characters. A conversion specifier consists of a percent (%) character 
followed by a character. The following list describes the characters with 
which each conversion specifier is replaced. 


Conversion 

Specifier Replaced with . . . 

%a the locale’s abbreviated weekday name 

%A the locale’s full weekday name 

%b the locale’s abbreviated month name 

% b the locale’s full month name 

%c the locale’s appropriate date and time representation 

%d the day of the month as a decimal number (01-31) 

%H the hour (24-hour clock) as a decimal number (00-23) 

%l the hour (12-hour clock) as a decimal number (00-12) 

(continued) 
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strftime 

(continued) 


Format a time string 
Conversion 


Specifier 

Replaced with . . . 

%j 

the day of the year as a decimal number (001-366) 

%m 

the month as a decimal number (01-12) 

%M 

the minute as a decimal number (00-59) 

%p 

the locale’s equivalent of the AM and PM designations 
associated with a 12-hour clock 

%S 

the second as a decimal number (00-61) 

%U 

the week number of the year (the first Sunday as the first 
day of week 1) as a decimal number (00-53) 

%w 

the weekday as a decimal number (0-6), where Sunday is 
0 

%W 

the week number of the year (the first Monday as the 
first day of week 1) as a decimal number (00-53) 

%x 

the locale’s appropriate date representation 

%x 

the locale’s appropriate time representation 

%y 

the year without the century as a decimal number 
(00-99) 

%Y 

the year with the century as a decimal number 

%z 

the time zone name or abbreviation; no characters 
indicates the time zone is not determinable 

%% 

a percent sign. 


No more than maxsize characters are placed into the array. The 
appropriate characters are determined by the lc_time category of the 
current locale and by the values contained in the structure pointed to by 
the argument timeptr. If copying takes place between objects that 
overlap or if the conversion specifier is not one of those listed above, the 
behavior is undefined. 


Portability ANSI 
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strftime Format a time string 
(continued) 

Returns This function returns the number of characters placed into the string 
pointed to by the argument s, not including the terminating NULL 
character. Otherwise, the strftime function returns a 0, and the 
contents of the s argument are indeterminate. 


See Also asctime, gmtime, localtime, setlocale 
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Stricmp Compare strings, case insensitive 
Synopsis § include <string.h> 
x = stricmp(a,b) ; 


int x; /* comparison result */ 

const char *a,*b; /* strings being compared */ 

Description This function compares two NULL -terminated strings using the ASCII 
collating sequence, but does not distinguish between uppercase and 
lowercase. 

The relative collating sequence of the strings is indicated by the sign of 
the return value, as follows: 


Return Meaning 

negative first string is below the second 

zero strings are equal 

positive first string is above the second 


This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability SAS/C 

Returns The sign of the return value indicates the relative collating sequence of 
the strings, as indicated above. 

Example ({include <stdio.h> 

{{include <string.h> 

void result(char *name f int r) 

{ 

char *p; 

if (r == 0) 

{ 

p = "is equal to"; 

) 
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Stricmp Compare strings, case insensitive 
(continued) 

if (r < 0) 

( 

p = "is less than"; 

) 

if (r > 0) 

( 

p = "is greater than"; 

} 

printf("?Ss string A %s string B\n" ,narae,p) ; 


void main(void) 

i 

char a [ 256 ] , b[ 256 ] ; 

while( 1 ) 

{ 

printf ( "Enter string A: "); 
if (fgets(a,sizeof (a) ,stdin) == NULL) 
( 

break; 

) 

printf ( "Enter string B: "); 

if ( fgets(b, sizeof (b) ,stdin) == NULL) 

{ 

break; 

) 

result ( "stricmp: " , stricmp( a,b) ) ; 

) 

printf ("\n") ; 


See Also strcmp, strncmp, strnicmp 
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strins 

Synopsis 


Description 


Portability 

Example 


Insert a string 
Kinclude <string.h> 
void strins(to, from) ; 

char *to; /* destination string */ 

const char *from; /* source string */ 

This function inserts the source string in front of the destination. Both 
strings must be NULL-terminated, and the destination is shifted to the 
right (upward in memory) to accommodate the source string. The final 
result is a single NULL-terminated string. 

Make sure that the destination area is large enough to hold both 
strings. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

ilinclude <stdio.h> 

^include <string.h> 

void main(void) 

{ 

char *here = "Here 
char now[30] ; 

strcpy(now, "and now"); 
printf("Xs, fts\n", here, now); 

strins(now, here); /* now => "Here and now" */ 

printf ( "Xs\n" ,now) ; 

} 


See Also 


strcat 
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strlen 

Synopsis 

Description 

Portability 

Returns 

Example 


Measure the length of a string 
((include <string.h> 
length = strlen(s) ; 

size_t length; /* number of bytes in s (before null) */ 
const char *s; 

This function returns the number of bytes in string s before the NULL 
terminator byte. 

The strlen function has a built-in version that is equivalent to the 
standard library version. The statement ((include <string.h> 
provides a default setting by which built-in functions are accessed. If you 
do not want the built-in function, you can enter an #undef strlen 
statement after including the file string. h. 

ANSI 

This function returns the number of bytes in the string before the NULL 
byte. 

x = strlen( "abc" ) ; /* x is 3 */ 

x = strlen(""); /* x is 0 */ 


See Also 


stolen 
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Strlwr Convert a string to lowercase 
Synopsis ft include <string.h> 
p = strlwr(s); 

char *p; /* return pointer (same as s) */ 

char *s; /* string pointer */ 


Description This function converts all alphabetic characters in the specified NULL- 
terminated string to lowercase, according to the 7-bit ASCII collating 
sequence. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability XENIX 


Returns This function returns the original string pointer. 
See Also stricmp, strupr, tolower, toupper 
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strmfe 

Synopsis 


Description 


Portability 
See Also 


Make a filename with an extension 

ifinclude <string.h> 

void strmf e ( newname , oldname , ext ) ; 

char *newname; /* new file name */ 

const char *oldname; /* old file name */ 

const char *ext; /* extension */ 

This function copies the old filename to the new name, deleting any 
extension. Then it appends the specified extension to the new filename, 
with an intervening period. For example: 


Old name 

Extension 

New name 

df 1 :myprog . c 

cc 

df 1 rmyprog . cc 

abc 

o 

abc . o 


The newname area must be large enough to accept the filename string 
and the separator. A safe size is FMSIZE which is defined in the 
dos . h header file. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

strmfn, strrafp 



524 Chapter 7 


Strmfn Make a filename from components 
Synopsis # include <string.h> 

void strmfn(f ile, drive, path, node, ext) 


char *file; 
const char *drive 
const char *path; 
const char *node; 
const char *ext; 


/* file name pointer */ 

/* drive code pointer */ 

/* directory path pointer */ 
/* node pointer */ 

/* extension pointer */ 


Description This function makes a filename from four possible components. The name 
is constructed as follows: 


drive : path/node . ext 

If the drive pointer is not NULL, the drive pointer is moved to the 
area pointed to by the file argument. Then, a colon is inserted unless 
one is already there. Next, if the path pointer is not NULL, it is 
appended to file, and the directory separator specified by —SLASH is 
added if necessary. The node string is appended next, unless it is NULL. 
Finally, if the ext pointer is not NULL, a period is appended to file, 
followed by the ext string. 

Make sure that the file pointer refers to an area which is large 
enough to hold the result. 

This function is not available if the —STRICT— ANSI flag has been 
defined. 

Portability SAS/C 

Example # include <stdio.h> 

Jfinclude <string.h> 

^include <dos.h> 

char buffer [FMSIZE ] ; 

void main(void) 

( 

/* The next statements both place "abc/def /ghi" */ 

/* into the buffer. */ 


printfC"', 'abc/def', 'ghi', ' ' \n" ) ; 
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strmfn Make a filename from components 
(continued) 


strmfn(buffer,NULL, "abc/def " , "ghi" ,NULL ) ; 
printf( "result = Ks\n\n", buffer); 

printfC"', 'abc/def/', 'ghi', ' * \n" ) ; 
strmfn(buf fer, NULL, "abc/def /" , "ghi" , NULL ) ; 
printf ( "result = %s\n\n", buffer); 

/* The next statements both generate "dfO:myf ile. str" */ 

printf (" ' df 0 ' , ", 'myfile', ’str'\n"); 
strmfn (buf fer , "df 0" ,NULL, "myfile" , "str" ) ; 
printf ( "result = £s\n\n", buffer); 

printf (" 'dfO :' , ", 'myfile', ’str'\n"); 
strmfn (buf fer , "df 0 : " ,NULL, "myfile" , "str" ) ; 
printf ( "result = Xs\n\n", buffer); 


See Also 


strmfe, strmfp 
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strmfp 

Synopsis 


Description 


Portability 
See Also 


Make a filename from the path or node 

((include <string.h> 

void strmfp( name, path, node) ; 

char *name; /* file name */ 

const char *path; /* directory path */ 
const char *node; /♦ node */ 

This function copies the path string (if it is not NULL) to the file name 
area and appends the —SLASH separator if the path string does not end 
with a slash or colon. Then, the node string is appended to the file 
name. —SLASH is an external character variable that defaults to a slash 
(/). 

The name area must be large enough to accept the filename string. 
This function is not available if the —STRICT— ANSI flag has been 
defined. 

SAS/C 

strmfe, strmfn 
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Strmid Return a substring from a string 
Synopsis H include <string.h> 

error = strmid(source, dest, pos, len) ; 


int error; 

const char *source; 

char *dest; 

int pos; 

int len; 


/* -1 if pos is beyond source, else 0 */ 
/* source pointer */ 

/* destination pointer */ 

/* starting position of dest in source */ 
/* length of substring */ 


Description The strmid function returns a pointer to a substring of the argument 

source beginning at character position pos that has a length of len. If 
len is greater than the length of the source offset at pos, then the rest 
of the string is copied to the destination pointed to by the dest 
argument. 

The destination string is null terminated. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


Returns If the pos value is beyond the length of the source value, then —1 is 
returned. Otherwise, 0 is returned. 

Portability SAS/C 

See Also strchr, strrchr, strstr 
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strncat 

Synopsis 


Description 

Portability 

Returns 

Example 


Concatenate strings, length limited 
((include <string.h> 
p = strncat(to, from.n) ; 

char *p; /* same as destination string pointer */ 

char *to; /* destination string pointer */ 

const char *from; /* source string pointer */ 
size_t n; /* maximum source length */ 

This function concatenates the source string to the end of the destination 
string. No more than n characters are moved from the source to the 
destination. A NULL byte is placed at the end of the destination in any 
case. 

ANSI 

This function returns a pointer that is the same as the first argument. 

finclude <stdio.h> 

((include <string.h> 

void main(void) 

{ 

char a [ 256 ] , b [ 256 ] ; 
int n; 

while( 1 ) 

{ 

printf ( "\nEnter string A: "); 
if (gets(a) == NULL) 

{ 

break ; 

) 

printf ( "Enter string B: "); 
if (gets(b) == NULL) 

{ 


) 


break; 



C Library Reference 529 


Strncat Concatenate strings, length limited 
(continued) 


printf ( "Enter maximum length N: "); 
if (scanf ( "Sd" , Sn) == EOF) 

{ 

break; 

} 

printf ( "strncat(A, B,N) : \"Xs\"\n", 
strncat(a,b,n) ) ; 

} 

printf ( "\n" ) ; 


See Also stpcpy, strcat 
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strncmp 

Synopsis 


Description 


Portability 

Example 


Compare strings, length limited 
((include <string.h> 
x = strncmp ( a, b,n) ; 

int x; /* comparison result */ 

const char *a,*b; /* strings being compared */ 

size_t n; 

This function compares two NULL-terminated strings using the ASCII 
collating sequence. No more than n characters are compared. 

The relative collating sequence of the strings is indicated by the sign of 
the return value, as follows: 


Return Meaning 

negative first string is below the second 

zero strings are equal 

positive first string is above the second 


If the strings have different lengths, the shorter one is treated as if it 
were extended with zeroes. 

ANSI 

((include <stdio.h> 

((include <string.h> 

void result(char *name, int r) 

{ 

char *p; 

if (r == 0) 

( 

p = "is equal to"; 

) 
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Strncmp Compare strings, length limited 
( continued ) 

if (r < 0) 

{ 

p = "is less than"; 

) 

if (r > 0) 

{ 

p = "is greater than"; 

) 

printf ("JSs string A *s string B\n" ,name,p) ; 

) 

void raain(void) 

( 

char a [ 256 ] , b [ 2 5 6 ] ; 
int n; 

while( 1 ) 

( 

printf( "Enter string A: "); 
if (fgets(a,sizeof (a) ,stdin) == NULL) 

I 

break; 

} 

printf( "Enter string B: "); 
if (fgets(b,sizeof (b) ,stdin) == NULL) 

( 

break; 

) 

printf ( "Enter maximum compare length: "); 
scanf ("55d" f £n) ; 

resultf "strncmp: " , strncmp(a,b,n) ) ; 

) 

printf ( "\n" ) ; 


See Also strcmp, strcmpi, stricmp, strnicmp 



532 Chapter 7 


strncpy 

Synopsis 


Description 


Portability 

Returns 


Copy a string, length limited 
((include <string.h> 
p = strncpy(to, from,n) ; 

char *p ; /* same as destination pointer */ 

char *to; /* destination pointer */ 

const char *from; /* source pointer */ 
size_t n; /* maximum source length */ 

This function copies the NULL-terminated source string to the destination 
area. The strncpy function always writes exactly n characters to the 
destination. If it reaches the NULL terminator before n characters are 
copied from the source, the destination is filled with NULL bytes. If the 
source string contains more than n non-NULL characters, the destination 
is not NULL-terminated. 

Be careful when using the strncpy function, because it is one of the 
few string functions that does not produce a NULL-terminated string 
under every condition. 

ANSI 

The strncpy function returns a pointer that is the same as the 
destination pointer. 


See Also stccpy, stpcpy, strcpy 
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strnicmp 

Synopsis 

Description 


Portability 

Returns 

Example 


Compare strings, case insensitive, length limited 
((include <string.h> 
x = strnicmp(a,b,n) ; 

int x; /* comparison result */ 

const char *a,*b; /* strings being compared */ 

size_t n; /* maximum comparison length */ 

This function compares two NULL-terminated strings using the ASCII 
collating sequence, but it does not distinguish between uppercase and 
lowercase. No more than n characters are compared. 

The relative collating sequence of the strings is indicated by the sign of 
the return value, as follows: 


Return Meaning 

negative first string is below the second 

zero strings are equal 

positive first string is above the second 


This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

The sign of the return value indicates the relative collating sequence of 
the strings, as noted above. 

((include <stdio.h> 

((include <string.h> 

void result(char *name, int r) 

{ 

char *p ; 

if (r == 0) 

{ 

p = "is equal to"; 
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Sfrnicmp Compare strings, case insensitive, length limited 
(continued) 

) 

if (r < 0) 

{ 

p = "is less than"; 

} 

if (r > 0) 

I 

p = "is greater than"; 

) 

printf ("Xs string A Xs string B\n",name, 


void main(void) 

{ 

char a [ 256 ] , b[ 256 ] ; 
size_t n; 

while( 1 ) 

( 

printf ( "Enter string A: "); 
if ( fgets(a, sizeof (a) f stdin) == NULL) 
( 

break; 

} 

printf ( "Enter string B: "); 
if (fgets(b, sizeof (b) , stdin) == NULL) 
{ 

break; 

} 

printf ( "Enter maximum compare length: 
scanf ( "Xd" , fin) ; 

result( "strnicmp: " ,strnicmp( a, b,n) ) ; 

) 

printf ( "\n" ) ; 


See Also strcmp, strcmpi, stricmp, strncmp 
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strnset Set a string to a value, length limited 
Synopsis # include <string.h> 
p = strnset(s,c,n) ; 


char *p ; /* return pointer (same as s) */ 

char *s; /* string pointer */ 

int c; /* value */ 

int n; /* maximum string length */ 

Description This function sets all bytes of a NULL-terminated string to the same value, 
not including the terminator byte. No more than n bytes are set. That is, 
if a NULL byte is not found by the time n bytes have been set, the 
operation stops. 

This function is not available if the _STRICT__ANSI flag has been 
defined. 


Portability XENIX 

Returns This function returns the original string pointer. 
See Also strset 
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strpbrk 

Synopsis 

Description 

Portability 

Returns 

Example 


Find a break character in a string 
Hinclude <string.h> 
p = strpbrk(s,b) ; 

char *p; /* points to break character in s */ 

const char *s; /* string to be scanned */ 

cosnt char *b; /* break characters */ 

This function scans string s to find the first occurrence of a character 
from break string b. 

ANSI 

If no character from string b is found in string s, a NULL pointer is 
returned. Otherwise, p is a pointer to the first break character. 

/* 

* Scan for commas, periods, and blanks. Display the tail 

* of the string each time a break character is found. 

*/ 

jfinclude <string.h> 
iinclude <stdio.h> 

char *p, s[ ] = "Hello, I must be going."; 

void main(void) 

I 

for (p = s; (p = strpbrk(p, " , . ")) != NULL; p++) 

{ 

printf ( "$s\n" ,p ) - 


) 


See Also 


stpbrk, strspn, strcspn 
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strrchr 

Synopsis 


Description 


Returns 

Portability 

Example 


Find the last occurrence of a character in a string 
Hinclude <string.h> 
p = strrchr (s,c) ; 

char *p; /* updated string pointer */ 

const char *s; /* input string pointer */ 
int c; /* character to be located */ 

The strrchr function searches an input string for the last occurrence of 
the character c. The strrchr function is the reverse of the strchr 
function. 

The input string must end with the NULL character (‘\0’). A protection 
or addressing exception may occur if the input string is not terminated 
with the NULL character. 

This function returns a character pointer to the last occurrence of the 
search character in the input string or NULL if the character is not 
found. If the search character is the NULL character (‘\0’), the pointer 
points to the NULL character at the end of the input string. 

ANSI 

Ifinclude <stdio.h> 

^include <string.h> 
idefine LENGTH 80 

void main(void) 

I 

char line[LENGTH] ; 
char *last_blank; 

FILE *m; 


/* Read a string addressed by line from */ 
/* the input file associated with m. */ 
fgets ( line , LENGTH, m) ; 
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Strrchr Find the last occurrence of a character in a string 
(continued) 

/* Find the last space character in the */ 
/* string line and save its location in */ 
/* last-blank. */ 

last-blank = strrchr (line, ' '); 

) 

See Also stpchr, stpchrn, strchr 
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strrev 

Synopsis 

Description 

Portability 

Returns 


Reverse a character string 
jfinclude <string.h> 
p = strrev( s ) ; 

char *p,*s; /* string pointer */ 

This function reverses a character string. In other words, it rotates the 
string about its midpoint such that the last character is first and the first 
is last. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

XENIX 

This function returns the same pointer that was passed to it. 
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strset Set a string to a value 
Synopsis jf include <string.h> 
p = strset(s,c ) ; 

char *p; /* return pointer (same as s) */ 

char *s ; /* string pointer */ 

int c; /* value */ 

Description This function sets all bytes of a NULL-terminated string to the same value, 
not including the terminator byte. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability XENIX 


Returns This function returns the original string pointer. 
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strsfn 

Synopsis 


Description 


Portability 

Example 


Split the filename 
Sinclude <string.h> 


void strsfn(file,drive,path, node, ext) ; 


const char *file; 
char *drive; 
char *path; 
char *node; 
char *ext; 


/* file name pointer */ 

/* drive code pointer */ 

/* directory path pointer */ 
/* node pointer */ 

/* extension pointer */ 


This function splits a filename into four possible components and places 
them into the drive, path, node, and ext strings. If any of the 
arguments is NULL, then that component is discarded. 

A complete filename is constructed as follows: 

drive : path/ node . ext 

When the strsfn function splits the file name, it leaves the colon 
attached to the drive string, but drops the leading or trailing 
punctuation characters. In other words, the path component does not 
end with a slash, and the ext component does not begin with a period. 
Slashes within the path component are preserved. 

Make sure that the drive, path, node, and ext pointers refer to 
areas that are large enough to hold the largest string that might be 
generated. This function does not check that any component lengths are 
exceeded, although it does copy the file string to an internal buffer of size 
FMSIZE and truncate it if it is too long. If you want to be absolutely sure 
that no overflows occur, make each component area FMSIZE bytes long. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


SAS/C 

/* This program splits file names that it reads */ 
/* from stdin. */ 


Sinclude <stdio.h> 
Sinclude <string.h> 
Sinclude <dos.h> 
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strsfn Split the filename 
(continued) 


/* After the next statement, the component strings are: */ 
/* drive => "" path => "abc/def" */ 
/* node => "ghi" ext => "" */ 
/* strsfn( "abc/def /ghi" , drive, path, node, ext) ; */ 
/* */ 
/* After the next statement, the component strings are: */ 
/* drive => "dfO:" path => "" */ 
/* node => "myfile" ext => "str" */ 
/* strsfn("dfO:myfile. str", drive, path, node, ext) ; */ 


void main(void) 

( 

char input [255] , drive [FNSIZE] ,path[FMSIZE] , 
node[FNSIZE] ,ext[FESIZEl ; 

while( 1 ) 

{ 

puts( "\nEnter file name...\n"); 
if (gets(input) == NULL) 

( 

break; 

) 

strsf n ( input .drive , path , node , ext ) ; 
printf ("DRIVE: \"*s\"\n" 

"PATH: \"*s\"\n" 

"NODE: \"*s\"\n" 

"EXT: \"Xs\"\n", 

drive, path, node, ext); 

) 

printf ( "\n" ) ; 


See Also stcgfn, strmfe, strmfn 
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Strspn Count the number of string characters in the set 
Synopsis # include <string.h> 
length = strspn(s,b); 


size_t length 
const char *s 
const char *b 


/* span length in bytes */ 

/* points to string being scanned */ 
/* points to character set string */ 


Description This function counts the number of characters in the input string s that 
are in the character set specified by string b. The scan always stops when 
the NULL terminator byte is reached. 

Returns This function returns the number of bytes that are in the specified 
character set. 


Portability ANSI 


Example finclude <stdio.h> 
((include <string.h> 


void main(void) 

{ 

char si [256] ,s2[256] ; 
while( 1 ) 

l 

printf ( "\nEnter test string: "); 

if ( f gets (si ,sizeof (si) ,stdin) == NULL) 

I 

break; 

) 

printf ( "Enter span string: n ); 
if ( fgets( s2 , sizeof (s2) ,stdin) == NULL) 
{ 

break; 

) 

printf ( "strspn: 55d\n" , strspn ( s 1 , s2) ) ; 

} 

printf ( "\n" ) ; 
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strspn Count the number of string characters in the set 
( continued ) 

See Also stcis, stcisn, strcspn 
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strsrt Sort a string pointer list 
Synopsis (f include <string.h> 
void strsrt( s ,n) ; 


char *s[); /* string pointer list */ 

int n; /* number of pointers in list */ 


Description This function performs a simple bubble sort of the string pointers in the 
specified list. It is particularly useful in conjunction with the getfnl and 
strbpl functions. For large lists, you usually get better performance 
using the tqsort function. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


Portability SAS/C 
Example /* 

* This program constructs an array of pointers to all normal 

* files in the current directory that have an extension of 

* .c. Then the array is sorted into ASCII order. 

*/ 

((include <stdio.h> 

((include <stdlib.h> 


extern long _0SERR; 


void main(void) 

( 

char names [ 3000 ] ,*pointers[ 300 ] ; 
int count, i; 

count = getfnlC'#?. c", names, sizeof (names) ,0) ; 

if (count > 0) 

( 

if (strbpl(pointers, 300, names) != count) 

( 

fprintf (stderr,"Too many file names\n"); 
exit ( EXIT-FAILURE ) ; 

) 

strsrt(pointers, count ) ; 
printf ( "Names Found: \n" ); 
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Strsrt Sort a string pointer list 
( continued ) 

for (i=0; i<count; i++) 

{ 

printf ( "55s\n" , pointers [ i ]) ; 

) 

) 

else 

{ 

if (_0SERR) 

( 

poserr( "FILES" ) ; 

) 

else 

( 

fprintf ( stderr , "Too many files\n"); 

} 

exit (EXIT-FAILURE) ; 

} 

) 

See Also getfnl, strbpl, tqsort 



C Library Reference 547 


Strstr Find a substring inside of a string 
Synopsis # include <string.h> 
p = strstr(s1 , s2) ; 

char *p ; /* pointer to substring in string.*/ 

const char *s1; /* string to search in. */ 

const char *s2; /* substring to search for. */ 


Description This function searches for a substring inside of a string and returns its 
position in the string. 

Portability ANSI 

Returns This function returns a pointer to substring s 2 within string s 1 . If it 
cannot find the substring, it returns a NULL pointer. 


Example /* look for something in 'McDonald's farm' */ 
((include <stdio.h> 

((include <string.h> 


void main(void) 

{ 

char *p; 

p = strstr ("Old McDonald had a farm, EIEIO", "arm"); 
if (p == NULL) 

( 

printf("This is odd, I thought it " 

"was in there\n"); 

} 

else 

{ 

/* This should print out: */ 

/* Found it, it goes: arm, EIEIO */ 
printf ( "Found it, it goes: £s\n", p); 

} 


See Also strchr, strmid, strrchr 



548 Chapter 7 


strtod 

Synopsis 


Description 


Portability 

Returns 


Example 


Convert a string to a double-precision floating-point number 
((include <stdlib.h> 


d = strtod(nptr, endptr); 


double d; 

/* 

converted number 

*1 

const char *nptr; 

/* 

string to convert 

*/ 

char **endptr; 

/* 

pointer to end of 

string */ 


This function converts a character string into a double-precision floating- 
point number. If the endptr pointer is not NULL, the function places a 
pointer to the following character into it. Leading white space is ignored. 
The strtod function consults the current locale information to 
determine the normal representation of a floating-point number for the 
current locale. 

ANSI 

This function returns the converted double-precision floating-point 
number. If it is unable to convert the input source string, it returns a 
value of 0. For values too large or too small to fit in a double-precision 
floating-point number, it returns a value that is plus or minus HUGE_VAL 
and sets the external integer errno to ERANGE. In the case of an 
underflow, it returns 0, and the external integer errno is set to 
ERANGE. 

/* Read a number and convert it to a double. */ 

((include <stdio.h> 

((include <stdlib.h> 

char buf [80 ] ; 
double d; 
char *p ; 

void main(void) 

( 

printf( "Enter a BIG number :\n"); 
fflush(stdout) ; 
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strtod Convert a string to a double-precision floating-point number 
( continued ) 

fgets(buf ,sizeof (buf ) ,stdin) ; 
d = strtod(buf, Sp ) ; 

printf("We got % If , with a remaining string " 

"of 'J5s'\n", d, p); 

) 

See Also scanf 



550 Chapter 7 


Strtok Get a token 
Synopsis # include <string.h> 
t = strtok (s,b) ; 

char *t ; /* token pointer */ 

char *s ; /* input string pointer or NULL */ 

const char *b; /* break character string pointer */ 

Description This function treats the input string as a series of one or more tokens 

separated by one or more characters from the break string. By making a 
sequence of calls to the strtok function, you can obtain the tokens in 
left-to-right order. To get the first (leftmost) token, supply a non-NULL 
pointer for the s argument. To get the next tokens, call the function 
repeatedly with a NULL pointer for the s argument, until you get a null 
return pointer to indicate that there are no more tokens. The break string 
can be changed from one call to another. 

Each time it is entered, the strtok function takes the following steps: 

1. If the input string is NULL, the strtok function gets the string 
pointer that was used on the preceding call. Otherwise, it uses the 
new input string pointer. 

2. The strtok function scans forward through the string to the next 
nonbreak character. If it is a NULL byte, the strtok function 
returns a value of NULL to indicate that there are no more tokens. 

3. The strtok function scans forward through the string to the next 
break character or the NULL terminator byte. In the former case, it 
writes a NULL byte into the string to terminate the token, and then 
scans forward until the next nonbreak character is found. In either 
case, it saves the final value of the string pointer for the next call 
and returns the token pointer. 

The input string gets changed as the scan progresses. Specifically, a 
null byte is written at the end of each token. 

Portability ANSI 


Returns A null pointer is returned when there are no more tokens. 
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StrtOk Get a token 
(continued) 

Example /* 

* This example breaks out words that are separated 

* by blanks or commas. The token pointer takes on 

* the following values as the program loops: 

* LOOP TOKEN 

* 1 "first" 

* 2 "second" 

* 3 "third" 

* 4 "fourth" 

* 5 NULL 

*/ 

iinclude <string.h> 

((include <stdio.h> 

char test [ ] = "first, second third, fourth"; 

void main(void) 

( 

char *token; 

token = strtok (test, " , "); 
while (token != NULL) 

I 

printf ( "!Ss\n" , token) ; 
token = strtok(NULL, " , "); 

) 

) 


See Also stptok, strcspn, strspn 
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strtol 

Synopsis 


Description 


Portability 

Returns 

Example 


Convert a string to a long integer 
((include <stdlib.h> 


r = strtol(p,np,base) ; 


long int r; 
const char *p; 
char **np; 
int base; 


/* result */ 

/* string pointer */ 

/* returns updated string pointer */ 
/* conversion base */ 


This function converts an ASCII string into a long integer according to 
the specified base, which can range from 2 to 36. Valid digit characters 
are 0 to 9, a to z, and A to Z. The highest allowable character is 
determined by the base. If the base is 0, then the string is analyzed to see 
if it is base 8, base 10, or base 16. If the string begins with Ox or OX, it 
is base 16; if the string begins with 0, it is base 8; if the string begins 
with a digit from 1 to 9, it is base 10. 

If the pointer np is not NULL, it specifies an area into which the 
updated string pointer is placed. That is, the pointer *np points to the 
first character in string p that is not a valid digit. 

The function skips blanks before starting the scan. 

ANSI 

This function returns the converted value. If it cannot do the conversion, 
it returns 0. If the converted value is too large or small to fit in a long 
integer, it returns LONG-MAX or LONG—MIN and sets the external integer 
errno to ERANGE. 


/* 

* Input a number from the user 
*/ 

((include <stdio.h> 

((include <stdlib.h> 


long age; 
char buf [256] ; 
char *p ; 
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strtol Convert a string to a long integer 
(continued) 

void raain(void) 

( 

printf ( "Please enter your age, followed by " 

"your name, on the same line\n"); 
fflush(stdout) ; 
gets(buf ) ; 

age = strtol(buf, Sp, 10); /* We only use decimal here */ 

printf ("Xs is Xld years old\n", p, age); 

) 

See Also strtoul 
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strtoul 

Synopsis 


Description 


Portability 

Returns 

Example 


Convert a string to an unsigned long integer 

((include <stdlib.h> 

r = strtoul(p,np,base) ; 

unsigned long int r; /* result */ 

const char *p; /* string pointer */ 

char **np; /* returns updated string pointer */ 

int base; /* conversion base */ 

This function converts an ASCII string into an unsigned long integer 
according to the specified base, which can range from 2 to 36. Valid digit 
characters are 0 to 9, a to z, and A to Z. The highest allowable character 
is determined by the base. If the base is 0, then the string is analyzed to 
see if it is base 8, base 10, or base 16. If the string begins with Ox or 
OX, it is base 16; if the string begins with 0, it is base 8; if the string 
begins with a digit from 1 to 9, it is base 10. 

If the pointer np is not NULL, it specifies an area into which the 
updated string pointer is placed. That is, the pointer *np points to the 
first character in string p that is not a valid digit. 

The function skips blanks before starting the scan. 

ANSI 

This function returns the converted value. If it cannot do the conversion, 
it returns 0. If the converted value is too large to fit in an unsigned long 
integer, it returns ULONG_MAX and sets the external integer errno to 
ERANGE. 

/* 

* Input a number from the user 
*/ 

((include <stdio.h> 

((include <stdlib.h> 

unsigned long age; 
char buf [ 256 ] ; 
char *p; 
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StrtOUl Convert a string to an unsigned long integer 
(continued) 

void main(void) 

( 

printf( "Please enter your age, followed by " 

"your name, on the same line\n"); 
f f lush( stdout ) ; 
gets(buf ) ; 

age = strtoul(buf, 6p, 10); /* We only use decimal here */ 

printf("JSs is Xld years old\n", p, age); 

) 

See Also strtol 
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Strupr Convert a string to uppercase 
Synopsis § include <string.h> 
p = strupr (s) ; 


char *p; /* return pointer (same as s) */ 

char *s; /* string pointer */ 

Description This function converts all alphabetic characters in the specified NULL- 
terminated string to uppercase using the 7-bit ASCII collating sequence. 

This function is not available if the _STRICT_ansi flag has been 
defined. 


Portability XENIX 

Returns This function returns the original string pointer. 
See Also stricmp, strlwr, tolower, toupper 
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strxfrm 

Synopsis 


Description 

Portability 

Returns 

Example 


Transform a string 
((include <string.h> 
len = strxfrm(s1, s2, n); 


size_t len; 
char *s1; 
const char * s 2 ; 
size_t n; 


/* length of transformed string */ 
/* pointer to transformed string */ 
/* string to transform */ 
/* max characters in transformed string */ 


This function transforms strings such that the strcmp function will give 
the same result when applied to two transformed strings as the strcoll 
function would give to the same strings before they were transformed. 

Because of the limitations of the ANSI specifications, this function does 
not completely handle the German collating rules. 

ANSI 


This function returns the length of the transformed string (excluding the 
NULL termination character). If a value is greater than the argument n, 
then the transformation could not fit in the output array, and the contents 
of the output array are indeterminate. 

/* Transform a string for comparison */ 

((include <stdio.h> 

((include <stdlib.h> 

((include <string.h> 

char *transform(char *string) 

{ 

int len; 
char *p ; 

/* Don't forget the NULL */ 
len = strxfrm( string, NULL, 0 ) + 1 ; 
if ( ( p = malloc(len)) != NULL) 

i 

strxfrm(string, p, len); 

) 

return(p) ; 


) 
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strxfrm Transform a string 
(continued) 


void main(int argc, char *argv[]) 

I 

int i; 

for (i=1; i<argc; i++) 

( 

printf("Xs ==> J5s\n", 

argv[i], transform(argv[i] ) ) ; 


) 


See Also setlocale, strcoll 
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stspfp 

Synopsis 

Description 

Portability 

Returns 

See Also 


Parse a file path 
Sinclude <string.h> 
error = stspfp(path,nx) ; 

int error; /* -1 for error, 0 for success */ 

const char *path; /* file path string */ 
int nx [16]; /* node index array */ 

This function parses a file path, which is a NULL-terminated string 
consisting of nodes separated by the —SLASH character. Each separator is 
replaced with a NULL byte, and the index to the first character of that 
node is placed into the node index array. The last entry in the array is 
followed by a —1. A leading separator in the path string is skipped. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

A return value of —1 indicates that the path contains more than 15 
nodes. 

stcgfe, stcgfn, stcgfp, strsfn 
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_stub 

Synopsis 

Description 


Default routine for undefined routines 
void _ stub( void) ; 

The —stub function is the default routine resolved by the linker for 
routines not found in libraries. By default, it puts up a requester 
indicating that the unwritten routine has been called. It is intended to 
allow development and testing of a program for which some of the 
routines have not been written (and, of course, are not expected to be 
called). 

For a list of the SAS/C libraries available, see Chapter 3, “Using the 
SAS/C Libraries.” 


Portability AmigaDOS 
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swmem 

Synopsis 


Description 

Portability 

Example 


Swap two memory blocks 

({include <string.h> 

void swmem( a ,b,n) ; 

void *a,*b; /* block pointers */ 

unsigned n; /* number of bytes */ 

This function swaps two blocks of memory. This function neither 
recognizes nor produces the NULL terminator byte usually found at the 
end of strings. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

{{include <stdio.h> 
iinclude <string.h> 

char buf [ ] = "String 1"; 
char buf 2 [ ] = "String 2"; 

void main(void) 

( 

printf("J5s ?Ss\n", 

buf, buf 2 ) ; /* Prints "String 1 String 2". */ 
swmem(buf, buf2, strlen(buf ) ) ; 
printf("Xs Ss\n" , 

buf, buf 2); /* Prints "String2 String 1". */ 

) 
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System Call the system command processor 
Synopsis i include <stdlib.h> 
error = system(cmd); 

int error; /* non-zero if error */ 

const char *cmd; /* command string */ 

Description This function invokes the system command processor and passes the cmd 
string to it. Under AmigaDOS, this function invokes the AmigaDOS 
Execute function. 

Portability ANSI 

Returns If the command processor cannot be invoked, a value of — 1 is returned, 
and additional error information can be found in the external integers 
errno and _OSERR. Otherwise, the function returns the value passed 
back by the command processor. 

Example § include <stdio.h> 

({include <stdlib.h> 

void main(void) 

{ 

int x; 

x = system! "dir ram:"); 

if (x < 0) 

( 

printf ( "System command failed\n"); 

) 

if (x > 0) 

I 

printf ("System command error 55d\n", x); 

) 


See Also errno, _OSERR 
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tan Tangent function 
Synopsis # include <math.h> 
r = tan(x) ; 

double r; /* result */ 
double x; /* angle */ 


Description The tan function computes the tangent of an angle expressed in radians. 
Portability ANSI 


See Also 


matherr 
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tanh 

Synopsis 

Description 

Portability 


Hyperbolic tangent function 
((include <math.h> 
r = tanh( x ) ; 

double r; /* result */ 

double x; /* angle */ 

The tanh function computes the normal hyperbolic tangent of the 
argument x. 

ANSI 


See Also matherr 
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tell 

Synopsis 


Description 


Portability 

Returns 


Get the level 1 file position 
({include <fcntl.h> 
apos = tell(fh) ; 

long apos; /* absolute file position */ 
int fh; /* file handle */ 

The tell function is equivalent to: 

apos = lseek( fh, OL, 1 ) ; 

The tell function returns a file position that can be used in a 
subsequent call to the lseek function to restore the file to the position at 
the time of the tell call. 

UNIX 

This function returns — 1L if an error occurs, in which case the external 
integers err no and _OSERR contain additional error information. 


See Also errno, ftell, lseek, open, _OSERR 
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telldir Get the directory position 
Synopsis if include <sys/dir.h> 
loc = telldir(dfd) ; 


long loc; /* current read position */ 

DIR *dfd; /* directory file descriptor */ 

Description This routine returns the current read position for the given directory file 
descriptor. This position is where the readdir function would obtain 
the next directory entry if it were called. The loc argument is also the 
value that you would pass to the seekdir function if you wanted to 
return directly to this same position. 

loc values are good only for the life of the directory file descriptor. If 
you close a directory and reopen it, the loc values are no longer valid. 

Portability UNIX 

Returns This function returns the location of the next directory entry. 

See Also closedir, opendir, readdir, seekdir 
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time 

Synopsis 


Description 

Portability 

Example 


Get the system time in seconds 

({include <time.h> 

timeval = time( timeptr ) ; 

time_t timeval; /* time value */ 

time_t *timeptr; /* pointer to time value storage */ 

This function returns the current time expressed as the number of 
seconds since 00:00:00 Greenwich Mean Time, January 1, 1970. If the 
timeptr pointer is not NULL, the time value is also stored in that 
location. 

ANSI 

{(include <stdio.h> 

((include <time.h> 

void main(void) 

I 

long t; 
time (St) ; 

printf ( "Current time is 5Ss\n" ,ctime( St) ) ; 

} 


See Also asctime, ctime, gmtime, localtime, tzset 



568 Chapter 7 


timecvt Convert a time_t value to an AmigaDOS DateStamp 


Synopsis § include <time.h> 


tp = — timecvt(t) ; 


struct DateStamp *tp; /* pointer to converted DateStamp */ 
time_t t; /* time value to convert */ 

Description This function converts a date and time in the format that the time 
function returns to the AmigaDOS DateStamp format. 

Portability AmigaDOS 

Returns This function returns a pointer to a DateStamp array. This array is 
considered read only and is valid only until the next call to the 
timecvt function. 


Example /* 

* Convert the current time. 
*/ 

((include <stdio.h> 

If include <time.h> 
i include <dos.h> 


void main(void) 

{ 

struct DateStamp *event; 

event = — timecvt (time( NULL) ) ; 

printf("Days since 1JAN78 = ?Sld\n" 

"Minutes after midnight = JSld\n" 

"Ticks past the minute = Xld\n", 
event->ds_Days, event->ds_Minute , event->ds_Tick ) ; 

} 


See Also 


mkt ime 
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timer 

Synopsis 


Description 


Portability 

Returns 


Get the system clock with microseconds 
((include <time.h> 
x = timer ( clock ) ; 
int x; 

unsigned int clock [ 2 J ; 

The timer function obtains the current setting of the system clock in the 
form of a two-integer array as follows: 

clock[0] => seconds 
clock[ 1] => microseconds 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

AmigaDOS 

If successful, this function returns a 0. Otherwise, it returns a —1. 
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tinymain Special version of the main function 

Synopsis flinclude <stdlib.h> 

void — stdargs tinyraain(line) ; 

char *line; /* ptr to command line that caused execution */ 

Description The tinymain function is provided for compatibility with previous 

releases. Use of tinymain increases the size of your executable 

module. Do not use tinymain. The functionality provided by 

tinymain is now automatically provided by the regular startup. 

Portability OLD 


See Also 


main 
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tmpfile 

Synopsis 

Description 


Portability 

Returns 

Example 


Open a temporary file stream 
jfinclude <stdio.h> 
fp = tmpf lie ( void) ; 

FILE *fp; /* pointer to temporary file stream */ 

This function opens a temporary file. The name of the temporary file is 
constructed from a combination of the first three characters of the 
program name, a string of characters based on the base stack pointer, 
and a sequential number (nn): 

T:progname . stack . T .nn 

The tmpfile function attempts to open files of increasing sequential 
numbers until it succeeds, or it has tried 99 times. If you do not have the 
argument T: assigned, the tmpfile function will never be able to create 
a temporary file. 

ANSI 

This function returns a file handle for a file that can be read or written. 
When this file is closed, it is automatically deleted. 

/* 

* Create a temporary file to hold a sort data set 
*/ 

finclude <stdio.h> 

void sortf ile(FILE *fpo, FILE * f pi ) 

{ 

/* Insert code for "World's Greatest File Sorter" */ 

/* in this routine... */ 

return; 

) 


void main(void) 

{ 


FILE *fp, *infp, *outfp; 
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tmpfile Open a temporary file stream 
( continued ) 

fp = tmpf ile( ) ; 
if (fp == NULL) 

I 

printf ("Can't create sort temp file\n"); 
return; 

) 

sortfile(fp, infp); 
sortfile(fp, outfp); 
fclose( fp) ; 


See Also open, close, tmpnam 
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tmpnam Create a temporary filename 
Synopsis § include <stdio.h> 
name = tmpnam(b); 

char *name; /* pointer to temporary file name */ 
char *b; /* pointer to name buffer or NULL */ 

Description This function creates a unique name that can be used for a temporary 
file. If the b pointer is not NULL, it should point to a buffer at least 
L_tmpnam bytes long, and the function returns that pointer. If b is 
NULL, then the function creates a buffer and returns a pointer to it. 
Subsequent calls to the tmpnam function may modify the buffer. 

Portability ANSI 

Returns This function returns a pointer to a temporary filename. 

See Also tmpfile 
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to..... 

Synopsis 

Description 


Portability 

Example 


Convert a character to ASCII, lowercase or uppercase 

((include <ctype.h> 

cc = toascii(c); 
cc = tolower(c ) ; 
cc = toupper(c); 

int cc; /* converted character */ 
int c; /* character to convert */ 

The toascii function resets all high-order bits, leaving only the lower 
seven. The tolower function tests if the argument c is an uppercase 
alphabetic character and, if so, converts it to lowercase. The toupper 
function is the reverse of the tolower function. 

You can use either characters or integers as arguments, but the 
functions are defined only over the integer range from —1 to 255. The 
functions, however, will return a result for values above 255, but the 
results are not necessarily correct and cannot be relied upon. The reason 
— 1 is included as a valid argument is to avoid a nonsensical result if you 
feed the EOF value to one of the macros or functions. EOF can be 
returned by the get char function and other I/O functions, and if you 
pass it to any of the character test functions, the return value will be 0. 

If you include the file ctype . h as shown above, these functions are 
actually defined as macros and produce inline code to perform the 
conversions. Without the ctype . h file, they are actual functions 
resolved in the standard library. If you want to use the function version 
but must include the file ctype . h for some other reason, use an 
#undef statement to undefine the macros after including the ctype . h 
file. 

The toascii function is not available if the _STRICT_ANSI flag has 
been defined. 

SAS/C toascii 
ANSI all others 

/* 

* The following program echoes each input 

* line in upper case. 

*/ 

Sinclude <stdio.h> 

((include <ctype.h> 
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to..... Convert a character to ASCII, lowercase or uppercase 
( continued ) 

void main(void) 

( 

char b [ 256 ] ,*p; 

while(gets(b) != NULL) 

( 

for (p = b; *p ! = ' \0 ' ; p++) 

{ 

*p = toupper(*p) ; 

) 

puts(b) ; 

) 


See Also 


_ctype, isascii, islower 
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tqsort Sort an array of text pointers 
Synopsis jfinclude <stdlib.h> 
void tqsort(ta,n) ; 

char *ta[]; /* pointer to text pointer array */ 

size_t n; /* number of elements in array */ 

Description The tqsort function sorts the specified data array using the ACM 271 
algorithm, more popularly known as Quicksort. During its operation, it 
calls on the strcmp comparison routine with pointers to the two array 
elements being compared. 

The ta array consists of pointers to NULL-terminated character strings. 
This function rearranges the pointers so that the strings are in ascending 
ASCII sequence. The sort is based on the contents of the strings rather 
than their physical address. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

Portability SAS/C 

See Also dqsort, f qsort, lqsort, qsort, sqsort 
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tzset Set the time zone variables 


Synopsis # include <time.h> 


void tzset( void) ; 


* If the _STRICT_ANSI flag 
these symbols are defined 
extern int — daylight; 
extern long — timezone; 

extern char * tzname[2]; 

extern char — tzstn[4); 
extern char — tzdtn [ 4 ] ; 
extern char *_TZ; 


has not 
in time. 


been defined, 
h: 


Description The tzset function assigns values to the time zone variables 

daylight, timezone, and tzname. These variables are then 

used by the local time function and other functions to correct from 
Greenwich Mean Time (GMT) to local time. 

The values for these variables are obtained from the character string 
pointer named _TZ, which has the following form: 

char *_TZ = " aaabbbccc" 

aaa is the three-letter abbreviation for the local standard time zone 
(for example, CST), and bbb is a number from —23 to 24 that specifies 
the number to be subtracted from GMT to obtain local standard time. 

Both aaa and bbb are required, ccc is the abbreviation for the local 
daylight savings time zone (for example, CDT), and it should be present 
only if daylight savings time is currently in effect. 

Initially, the _TZ pointer is set to NULL. It should be initialized with 
the address of a string corresponding to the correct time zone. If _TZ is 
NULL, the tzset function uses the default string CDT6. 

When the tzset function is called, the timezone integer is 

loaded with the number of seconds that must be subtracted from GMT to 

get the local time. Next, the daylight integer is loaded with 0 if the 

ccc portion of the _TZ pointer is absent and 1 if ccc is present. Then, 

the aaa and ccc parts are copied to tzstn and tzdtn, 

respectively, with NULL terminators. Finally, tzname [ 0 ] and 

tzname [ 1 ] are loaded with pointers to tzstn and tzdtn, 

respectively. 

The symbols defined in the file time . h are not available if the 
STRICT ANSI flag has been defined. 
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tzset Set the time zone variables 

(continued) 

Portability XENIX 


See Also 


localtime 
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ungetc 

Synopsis 


Description 


Portability 

Returns 

Example 


Push input character back 
jfinclude <stdio.h> 
r = ungetc(c, fp) ; 

int r; /* return character or code */ 

int c; /* character to be pushed back */ 

FILE *fp; /* file pointer */ 

This function pushes a character back to the specified level 2 input file. 
The character need not be the same as the one that was most recently 
read. However, before calling the ungetc function, you must have read 
at least one character using the f getc function or one of the other level 
2 input functions. Also, you can only push back one character; if you call 
the ungetc function more than once between input functions, the results 
are undefined. 

ANSI 

Normally, the ungetc function returns the character that was pushed 
back. However, if the end-of-file has been reached or if no characters 
have been read yet, the value EOF is returned. 

Kinclude <stdio.h> 

void main(void) 

{ 

int c; 

while( 1 ) 

{ 

printf("Loop 1...\n"); 
while((c = getchar()) != EOF) 

( 

if (isalpha(c)) 

( 

putchar (c) ; 

) 

else 

( 

break; 

i 

i 
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ungetc Push input character back 
( continued ) 

ungetc(c, stdin); 
printf ( "\n\nLoop 2...\n"); 
while((c » getchar()) != EOF) 
( 

if (isalpha(c) == 0) 

{ 

putchar(c) ; 

) 

else 

I 

break; 

1 

) 

ungetc(c, stdin); 

) 

printf ( "\n\nDone\n" ) ; 

i 
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unlink 

Synopsis 


Description 


Portability 

Returns 

Example 


Remove a file 
((include <stdio.h> 
error = unlink(name) ; 

int error; /* non-zero if error */ 

const char *name; /* file name */ 

This function removes the specified file from the system. The file name 
argument can include a path, but it cannot include wild card characters. 
That is, you can remove only one file at a time. 

The unlink function is provided for compatibility with some versions 
of UNIX. 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

UNIX 

If a nonzero value is returned, some type of error occurred, and 
additional information can be found in the external integers err no and 
—OSERR. The most common errors occur when you try to remove a file 
that doesn’t exist, that is marked as read-only, or that is in use. 

/* 

* This program removes all files specified 

* in the argument list. It does not allow 

* wild card characters in the file names. 

*/ 

((include <stdio.h> 

((include <stdlib.h> 

void main(int argc, char *argv[]) 

( 

int i; /* loop counter */ 

/* exit code, non-zero if any failures */ 
int ret = EXIT_SUCCESS ; 
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unlink Remove a file 
(continued) 

for (i = 1; 1 < argc; i++) 

{ 

if (unlink(argv[i] ) ) 

{ 

perror ( "RMV" ) ; 
ret = EXIT-FAILURE; 

} 

} 

exit(ret) ; 

) 

See Also errno, _OSERR, remove 
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utpack 

Synopsis 


Description 


Portability 

Returns 


Pack UNIX time 
((include <time.h> 
ut = utpack(x) ; 

long ut; /* packed UNIX time */ 

const char *x; /* unpacked UNIX time */ 

This function packs the 32-bit time value that is traditionally used in 
UNIX systems. This value is the number of seconds since 00:00:00, 
January 1, 1970. The time function returns the system clock in this 
form relative to Greenwich Mean Time. 

The unpacked time is a 6-byte array in the following format: 


Byte Contents 


x| 

0! 

year - 1970 ( — 128 to 127) 

x| 

1 ] 

month (1 to 12) 

X| 

2] 

day (1 to 31) 

x| 

31 

hour (0 to 23) 

X| 

*1] 

minute (0 to 59) 

X| 

5] 

second (0 to 59) 


Although this array is similar to the one produced by the get elk 
function and used by the stpdate function, the year is biased relative to 
1970 instead of 1980. The year is a signed character and can be 
negative. A value of —3, for example, is 1967 (in other words, 

1970 - 3). 

This function is not available if the _STRICT_ANSI flag has been 
defined. 

SAS/C 

This function returns a packed long integer, as described above. 
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Utpack Pack UNIX time 
(continued) 

Example /* 

* Get a file time and subtract 10 years from it. 

* No error checks. 

*/ 

((include <stdio.h> 

((include <stdlib.h> 

((include <time.h> 

((include <dos.h> 

void main(int argc, char *argv[]) 

i 

char tt [ 6 ] ; 
long ft,ut; 

ft = getft(argv[ 1 ] ) ; 
utunpk(ft, tt); 
tt [ 0 ] -= 10; 
ut = utpack(tt) ; 

printf("File time is: Ss\n" f ctirae( gut) ) ; 


See Also 


ctime, getclk, gmtime, localtime, stpdate, time, utunpk 
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utunpk 

Synopsis 


Description 


Unpack UNIX time 

Sinclude <tirae.h> 

void utunpk (ut, x) ; 

long ut; /* packed UNIX time */ 
char *x; /* unpacked UNIX time */ 

This function unpacks the 32-bit time value that is traditionally used in 
UNIX systems. This value is the number of seconds since 00:00:00, 
January 1, 1970. The time function returns the system clock in this 
form relative to Greenwich Mean Time. 

The unpacked time is a 6-byte array in the following format: 


Byte Contents 


X| 

0] 

year - 1970 ( — 128 to 127) 

x I 

1 ] 

month (1 to 12) 

x| 

2] 

day (1 to 31) 

X| 

31 

hour (0 to 23) 

X| 

'll 

minute (0 to 59) 

X| 

51 

second (0 to 59) 


Although this array is similar to the one produced by the getclk 
function and used by the stpdate function, the year is biased relative to 
1970 instead of 1980. So, if you use the utunpk function followed by 
the stpdate function, you must subtract 10 from x [ 0 ] before the 
stpdate call. The year is a signed character and can be negative. A 
value of —3, for example, is 1967 (in other words, 1970 — 3). 

This function is not available if the _STRICT_ANSI flag has been 
defined. 


Portability SAS/C 
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Utunpk Unpack UNIX time 
(continued) 

Example /* 

* Get a file time and subtract 10 years from it. 

* No error checks. 

*/ 

((include <stdio.h> 

((include <stdlib.h> 

(f include <time.h> 

^include <dos.h> 

void main(int argc, char *argv[J) 

{ 

char tt [ 6 ] ; 
long ft,ut; 

ft = getft(argv[ 1 ] ) ; 
utunpk(ft, tt); 
tt [ 0 ] -= 10; 
ut = utpack(tt); 

printf("File time is: Xs\n" , ctime(6ut) ) ; 


See Also ctime, getclk, gmtime, localtime, stpdate, time, utpack 
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va_arg 

Synopsis 

Description 


Portability 

Returns 


Get an argument from a varying-length argument list 
iinclude <stdarg.h> 

(arg_type) va_arg( va_list ap, arg_type); 

The va_arg macro returns the value of the next argument in a varying- 
length argument list. 

The first argument, ap, is a work area of type va_list, which is used 
by various macros defined in the file stdarg.h. (The va_list must be 
initialized by a previous use of the va_start macro, and a 
corresponding va_end should be called when processing of the 
arguments is finished. 

The second argument, arg_type, is the type of the argument that is 
expected. The arg_type argument must be written in such a form that 
arg_type * is the type of a pointer to an element of that type. For 
example, char is a valid arg_type because char * is the type of a 
pointer to a character, int ( * ) ( ) is not a valid second argument to the 
va_arg macro because int (*)()* is not a valid type. (You can use 
typedef declarations to create usable synonyms of this sort for any 
type.) 

The results of the va_arg macro are unpredictable if the argument 
values are not appropriate. 

In certain cases, arguments are converted when they are passed to 
another type. For instance, char and short arguments are converted to 
int, float to double, and array to pointer. When parameters of this 
sort are expected, the va_arg macro must be issued with the type after 
conversion. For example, va_arg(ap, float) may fail to access a 
float argument value correctly, so va_arg(ap, double) should be 
used. 

Note: There is no way to test whether a particular argument is the 
last one in the list. Attempting to access arguments after the last one in 
the list produces unpredictable results. 

ANSI 

The va_arg macro returns the value of the next argument in the list. 

The type is always the same as the second argument to the va_arg 


macro. 
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va_arg 

( continued ) 

Example 


Get an argument from a varying-length argument list 


/* 

* This example shows a function named concat, 

* which can be used to concatenate any number 

* of strings. A simple call is concat(3,a,b,c) . 

* This should have the same effect as 

* 

* strcat (a,b); 

* strcat (a,c); 

* The first argument is the total number of strings. 
*/ 

((include <stdarg.h> 

((include <string.h> 

((include <stdio.h> 

void concat (int count, . ..); 

void main(void) 

{ 

char str [ 20 ] = "abed"; 

concat (4 , str, "efgh" , "i jkl" , "mnop" ) ; 

printf("The concatenated string = JSs\n",str); 


void concat (int count, ...) 

( 

va_list ap; 

char *target, *source; 

if (count <=1) 
return; 


va_start(ap, count); 



C Library Reference 589 


va_arg Get an argument from a varying-length argument list 
( continued ) 


/* Get target string */ 
target = va_arg (ap, char *); 

/* Point to string end */ 
target += strlen(target) ; 

while (—count > 0) 

{ 

/* Get next source string */ 
source = va_arg(ap, char *); 

/* Copy chars to target */ 
while (^source) 

*target++ = *source++; 

) 

/* Add final null */ 

♦target = ' \0 ' ; 

/* End arg list processing */ 
return; 

) 


See Also va_end, va_start 
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va_end 

Synopsis 

Description 


Portability 
Example 
See Also 


End varying-length argument list processing 
iinclude <stdarg.h> 
void va_end( va_list ap); 

The va_end macro completes processing of a varying-length argument 
list. The argument ap is a work area of type va_list, which is used by 
various macros defined in the file stdarg. h. 

After the va_end macro is called, the va_start macro must be 
called again before the va_arg macro can be used. 

In this implementation, use of the va_end macro in varying-length 
argument list processing is not required. However, in other 
implementations, failure to issue the va_end macro may cause program 
failures on return from the function that issued the va_start macro. 

ANSI 

See the example for the va_arg macro. 
va_arg, va_start 
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va_start 

Synopsis 

Description 


Portability 
Example 
See Also 


Begin varying-length argument list processing 

#include <stdarg.h> 

void va_start( va_list ap, arg_name); 

The va_start macro initializes processing of a varying-length argument 
list. The first argument, ap, is a work area of type va_list, which is 
used by various macros defined in the file stdarg.h. The second 
argument, arg_name, is the name of the parameter to the calling 
function after which the varying part of the parameter list begins (the 
parameter immediately before the 

The results of the va_start macro are unpredictable if the argument 
values are not appropriate. 

ANSI 

See the example for the va_arg macro. 
va_arg, va_end 
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vfprintf Formatted write of a varying-length argument list to a file 

Synopsis § include <stdarg.h> 

^include <stdio.h> 


n = vfprintf(fp, ctl, args); 


int n; /* number of characters written */ 

/* or -1 for error */ 

FILE *fp; /* file to be written to */ 

const char *ctl; /* control string specifying formatting */ 

va_list args; /* items to be formatted */ 


Description This function is identical in capabilities to the f print f function, except 
that the argument list is passed as a va_list instead of on the stack. 
The argument list args must be initialized by the caller with a 
va_start macro (and any preceding va_arg macros that it wants to 
call). When terminated, it is the responsibility of the caller to call the 
va_end macro on the argument list. 

Portability ANSI 

Returns This function returns the number of characters written or, in the case of 
an error, a —1. 


Example ((include <stdio.h> 
((include <stdarg.h> 


/* My own error function for a given error number */ 
void myerr(FILE *fp, int ernum, char *string, ...) 

( 

va_list arglist; 


va_start(arglist, string); 


fprintf ( fp, "ERR-?Sd : \n" , ernum) ; 
vfprintf (fp, string, arglist); 


} 


va_end( arglist) ; 
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vfprintf Formatted write of a varying-length argument list to a file 
( continued ) 


void raain(void) 

( 

myerr(stderr , 205, sys_errlist [ 205 ] ) ; 

} 


See Also fprintf 
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vprintf 

Synopsis 

Description 

Portability 

Returns 

Example 


Formatted write of a varying-length argument list to standard output 

((include <stdarg.h> 

((include <stdio.h> 

x = vprintf (ctl, args); 

int x; /* number of characters written */ 

/* or -1 for error */ 

const char *ctl; /* control string specifying formatting */ 
va_list args; /* items to be formatted */ 

This function is identical in capabilities to the printf function, except 
that the argument list is passed as a va_list instead of on the stack. 
The argument list args must be initialized by the caller with a 
va_start macro (and any preceding va_arg macros that it wants to 
call). When terminated, it is the responsibility of the caller to call the 
va_end macro on the argument list. 

ANSI 

This function returns the number of characters written or, in the case of 
an error, a —1. 

((include <stdio.h> 

((include <stdarg.h> 

/* 

* My own error function for a given error number 
*/ 

void myerr(int ernum, char *string, ...) 

{ 

va_list arglist; 

va_start(arglist, string); 

printf ( "ERR-ftd: ", ernum); 
vprintf ( string, arglist); 


} 


va_end( arglist) ; 
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vprintf Formatted write of a varying-length argument list to standard output 
(continued) 

void main(void) 

{ 

myerr(205, _sys_errlist [ 205 J ) ; 

) 


See Also printf 
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vsprintf Formatted write of a varying-length argument list to a string 

Synopsis § include <stdarg.h> 

((include <stdio.h> 


x = vsprintf (buf , ctl, args); 


int x; /* number of characters placed in the */ 

/* output buffer */ 

char *buf; /* String for resulting image */ 

const char *ctl; /* control string specifying formatting */ 

va_list args; /* items to be formatted */ 


Description This function is identical in capabilities to the sprintf function, except 
that the argument list is passed as a va_list instead of on the stack. 
The argument list args must be initialized by the caller with a 
va_start macro (and any preceding va_arg macros that it wants to 
call). When terminated, it is the responsibility of the caller to call the 
va_end macro on the argument list. 

Portability ANSI 


Returns This function returns the number of characters placed in the output 
buffer (excluding the terminating NULL byte). 

Example (f include <stdio.h> 

((include <stdarg.h> 


/* 

* Format an arbitrary message into a buffer 
*/ 

void getmsg(char *buffer, char *string, ...) 

{ 

va_list arglist; 


va_start(arglist, string); 
vsprintf (buf fer, string, arglist); 


va_end( arglist) ; 
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vsprintf Formatted write of a varying-length argument list to a string 
(continued) 

void main(void) 

{ 

char buf [256 ] ; 

getmsg(buf, "Formatted with Sd argument. \n" , 1); 
printf (buf ) ; 

) 


See Also s printf 
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wait, waitm Wait for single or multiple child processes to complete 

Synopsis # include <dos.h> 

cc = wait(procid) ; 
coraplist = waitm(proclist) ; 


int cc; /* child's completion code */ 

struct ProcID *procid; /* pointer to process ID structure */ 

struct ProcID *complist; /* pointer to linked list of */ 

/* completed process IDs */ 

struct ProcID **proclist; /* address of pointer to linked */ 
/* list of process IDs */ 


Description After a process creates a child with the fork and f orkv functions, the 
parent continues to execute until it calls either the wait or waitm 
function; that is, the parent and child are multiprogrammed. When the 
child process completes, the parent process can get its completion code 
with the wait or waitm function. 

See the description of the forkl and f orkv functions for more 
information. 

Portability SAS/C 

Returns This function returns the integer completion code of the child process. 

Example See the example under the forkl and f orkv functions. 


See Also exit, forkl, f orkv, AmigaDOS functions LoadSeg and 
CreateProc ( The AmigaDOS Manual, 3rd Edition) 
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wcstombs 

Synopsis 


Description 

Portability 


Convert a wide-character string to a multibyte string 
Hinclude <stdlib.h> 


length = wcstombs(s, pwcs, n); 


size_t length; 
char *s ; 

const wchar_t *pwcs; 
size_t n; 


/* length or state information */ 

/* pointer to characters */ 

/* pointer to wide-character string */ 

/* maximum number of characters to look at */ 


This function converts a NULL-terminated wide-character string to a 
NULL-terminated multibyte string. The wcstombs function for the 
current locale is passed the input parameters, and the result is returned. 

ANSI 


See Also mblen, wctomb 
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WCtomb Map a wide character to a multibyte character 
Synopsis ((include <stdlib.h> 

length = wctomb(s, wc); 

int length; /* length or state information */ 
char *s; /* pointer to characters or NULL */ 

wchar_t wc; /* wide character */ 

Description This function converts a wide character to a multibyte character 

sequence. The wctomb function for the current locale is passed the input 
parameters, and the result is returned. 

Portability ANSI 


See Also mblen, wcstombs 
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write 

Synopsis 


Description 


Portability 

Returns 

See Also 


Write to a level 1 file 


((include <fcntl.h> 


count = write(fh,buffer,length) ; 


int count; 
int fh; 
void *buffer; 
unsigned int length; 


/* actual bytes read or written */ 

/* file handle */ 

/* data buffer */ 

/* number of bytes to read or write */ 


This function writes a level 1 file whose handle was returned by the 
creat or open function. Under normal circumstances, the value 
returned should match the buffer length. If this value is — 1 or greater 
than the requested length, then some type of error occurred, and you 
should consult the external integers errno and _OSERR. If the actual 
length is less than the requested length when reading, this usually means 
that the file is exhausted. Similarly, if the actual length is less than the 
requested length for a write operation, this usually means that the device 
has no more space available. In both of these cases, it is still a good idea 
to check the external integers errno and _OSERR just in case some 
malfunction caused the short count. 

Level 1 files are automatically closed by the exit function, which is 
usually called for you when the program terminates. 

UNIX 

If the operation is successful, this function returns the actual number of 
bytes transferred. Otherwise, it returns — 1 and places error information 
in the external integers errno and _OSERR. 

errno, fwrite, open, _OSERR, read 
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-XCEXIT 

Synopsis 

Description 


Portability 
See Also 


Terminate the program 
((include <stdlib.h> 
void _XCEXIT( lcode) ; 
long lcode; 

This function terminates execution of the current program and returns 
control to the parent program. —XCEXIT calls the standard termination 
routines. The parameter lcode is a value from 0 to 255 that gets passed 
back to the parent. By convention, a value of 0 indicates success. 

Normally, your program should call the exit or exit functions. 

—XCEXIT is a symbol defined in the startup code, so it does not exist 
when you use a startup file or shared library that you have created. 

If you are linking a shared library and you get a reference to XCEXIT 
as an undefined symbol, then you are linking in code that is attempting to 
call either exit, abort, or another function that makes the program 
terminate. From within a shared library, you must not call any library 
functions that terminate your program. For example, you cannot call 

exit, exit, or abort from a shared library. You also cannot use 

set jmp and longjmp to jump across a call from the program into the 
library. 

SAS/C 

exit, exit 
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Introduction 

The SAS/C Development System C+ + libraries contain class and 
function definitions for managing memory, manipulating complex 
numbers, and performing input and output, including formatting strings. 
These class and function definitions are declared in the header files in the 
cxxinclude: directory. This chapter describes the contents of this 
directory. 

You can use almost any C function in your C+ + programs. To use a C 
function, simply include any necessary C header files. The only exceptions 
are the set jrap and longjmp functions. Using longjmp may cause 
destructors not to be called for automatic objects. The results are 
unpredictable. If you use C I/O functions as well as C+ + I/O objects in 
your program, use stdiostream objects for I/O instead of f stream 
objects. 

Any include file in the include : directory is assumed to have "C" 
linkage. In other words, the compiler treats the file as if it is enclosed in 



extern "C" { 


/* header file */ 


Header files from other directories have C+ + linkage unless you 
override this linkage by enclosing the file in extern "C" { }. 

There is not yet an ANSI Standard for C+ +, but when one is 
developed, ANSI compatibility will take precedence over compatibility 
with the C + + language as described in The C+ + Programming 
Language, Second Edition. 
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Managing Memory (new.h) 

The new.h header file declares operators and a function that allow you 
to allocate and free memory. 

new.h contains the following prototypes: 

void* operator new(size_t size); 

allocates a block of dynamic memory of size bytes. If insufficient free 
dynamic memory is available and a new-handier function is currently 
defined (see set_new_handler ( ), below), the new-handier is 
called. When the new-handier returns, operator new tries again to 
allocate memory and if that fails, again calls the new-handier. This 
process repeats until either operator new can allocate some 
dynamic memory or the new-handier is removed. 

You can use operator new to create new I/O streams. See 
“Performing C+ + I/O” for more information, 
void operator delete(void* ptr ) ; 

frees the block of dynamic memory pointed to by ptr. The ptr must 
point to a block of memory allocated by operator new. 
void ( *set_new_handler ( void( *handler ) ( ) ))(); 

defines a pointer to a function (a new-handier) to handle out-of-memory 
conditions detected by operator new. The new-handier is called if 
operator new cannot allocate any dynamic memory. The new- 
handier should free some memory before returning to its caller or an 
endless loop may result. If it cannot free any memory, the new- 
handier should do one of the following: 

□ terminate the program using exit or abort. 

□ remove itself as a new-handier by calling set_new_handler ( ) 
with NULL or a pointer to some other handler. 

The new-handier function takes no arguments and returns void. The 
set_new_handler ( ) function returns the previous new-handier or 
NULL if there was not a previous new-handier. 



Manipulating Complex Numbers (complex.h) 

A complex number is a number of the following form: 

a + b yr 

This notation is equivalent to a+bi, where i is mathematical notation for 

VT 

a is the “real part,” and b is the “imaginary part.” In this book, complex 
numbers are shown as ( a , b ) . 

The functions and operators that allow you to manipulate complex 
numbers are implemented in class complex. The definition of 
class complex overloads the standard input, output, arithmetic, 
comparison, and assignment operators of C++, as well as the standard 
names of the exponential, logarithm, power, square root, and 
trigonometric functions (sine, cosine, hyperbolic sine, and hyperbolic 
cosine). Declarations for these functions and operators are in the header 
file complex . h. 

The following sections describe the contents of complex . h. The 
descriptions are organized as follows: 

constructors and conversion operators 

include constructors and conversion operators for complex object 
variables. 

cartesian and polar coordinate functions 

include descriptions of abs( ), arg( ), con j ( ), imag( ), norm( ), 
polar( ), and real( ). 

exponential, logarithmic, power, and square root functions 

include descriptions of exp( ), log( ), pow( ), and sqrt( ). 
trigonometric and hyperbolic functions 

include descriptions of sin( ), cos( ), sinh( ), and cosh( ). 
operators 

include the operators available for the complex library (+, *, ==, and 
so on). 

complex I/O operators 

include the insertion and extraction operators << and >>. 

Each set of function descriptions includes a synopsis and description of 
the function. The description includes any appropriate diagnostic or 
cautionary information. 
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Note: Some of the complex library functions call SAS/C math library 
functions. If you find you need more information on error handling for 
math functions, or you need more information about functions called by 
the complex library functions, refer to Chapter 7, “C Library Reference.” 
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complex() 

Synopsis 


Description 


Constructors and conversion operators 

((include <complex.h> 

class complex 
( 

public: 

complex ( ) ; 

complex (double real, double imag = 0.0); 


The following constructors are defined for class complex: 
complex ( ) ; 

enables you to declare complex variables without initializing them, 
static and external complex variables declared without an initializer 
have an initial value of (0,0); other uninitialized complex variables 
have an undefined initial value, 
complex ( double real, double imag = 0.0); 

allows explicit initialization of complex variables. For example, the 
following two statements are valid: 

complex cl ( 1 .0, 2.0) ; 

complex c2 (1.0); // The imaginary part is 0.0. 

This constructor also allows for implicit conversion from arithmetic 
types to complex values. For example, the following two statements 
are valid: 

complex c3 = 3.4; // c3 is (3.4, 0.0). 

c3= 1 0 ; // c3 is (10.0, 0.0). 

Using this constructor, you can also create complex values within 
expressions. For example: 

c2 = c3 + complex (1.2, 3.5); // Uses complex: : operator +. 

The temporary object created by the expression complex ( 1 . 2 , 3 . 5 ) 
gets destroyed. 
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abs(), arg(), 
con](), imag(), 
normO, polarJJ, 
realjj 

Synopsis 


Description 


Cartesian and polar coordinate functions 


((include <complex.h> 

class complex 

1 

public: 

friend double abs(complex c); 

friend double arg(complex c); 

friend complex conj (complex c); 

friend double imag(complex c); 

friend double norm(complex c); 

friend complex polar(double r, double t); 

friend double real(complex c); 

); 


The following list describes the functions defined for class complex. 
In these descriptions, d, r, and t are of type double, and c and z are 
of type complex. 

d = abs(c) 

returns the absolute value (magnitude) of c. 
d = arg(c) 

returns the angle of c (measured in radians) in the half-open interval 
(-7U to 7l). 
z = conj(c) 

returns the conjugation of c. If c is ( x , y ) , then con j ( c ) is 
(x,-y). 
d = imag(c) 

returns the imaginary part of c. 
d = norm(c) 

returns the square of the magnitude of c. 
z = polar(r, t) 

returns a complex number. The arguments represent a pair of polar 
coordinates where r is the magnitude and t is the angle (measured in 
radians), polar ( r , t ) is defined by the formula r*e 1 * t . 

d = real ( c ) 

returns the real part of c. 
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exp{), log(), 
pow{), sqrtO 

Synopsis 


Description 


Returns 


Exponential, logarithmic, power, and square root functions 


{(include <complex.h> 


class complex 

I 

public: 

friend complex 
friend complex 
friend complex 
friend complex 
friend complex 
friend complex 
friend complex 


exp( complex c) ; 
log(complex c) ; 
pow(double c, complex b); 
pow( complex c, int b); 
pow( complex c, double b); 
pow(complex c, complex b); 
sqrt( complex c); 


The following list describes the additional functions defined for class 
complex. These function names are overloaded by the C+ + libraries. 

In these descriptions, z is of type complex, and c and b are of the types 
indicated by the function prototypes in the Synopsis. 

z = exp(c) 
returns e c . 
z = log(c) 

returns the natural logarithm of c. When cis (0,0), log(c) 
returns ( -HUGE , 0 ) , and errno is set to EDOM, 
z = pow(c, b) 
returns c b . 
z = sqrt(c) 

returns the square root of c that is contained in the first or fourth 
quadrant of the complex plane. 

In all overflow cases, errno is set to ERANGE. 

For the log( ) function, if overflow is caused by the real part of c 
being small or the imaginary part of c being large, then exp(c) returns 
(0,0) and errno is set to ERANGE. 
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exp(), log(), Exponential, logarithmic, power, and square root functions 

pow(), sqrto 

(continued) 


If the real part of c is large enough to cause overflow, exp ( c ) returns 
different values depending on the sine and cosine of the imaginary part of 
c. The real portion of a complex number c depends on the 
cos(imag(c)), and the imaginary part depends on the 
s in ( imag ( c ) ) . The following table shows the values returned by 
exp ( c ) when the real part of c is large enough to cause overflow. 

HUGE corresponds to the largest representable double. 


cos ( imag ( c ) ) 

sin ( imag ( c ) ) 

exp(c) returns 

positive 

positive 

(HUGE, HUGE) 

positive 

negative 

(HUGE, -HUGE) 

negative 

positive 

(-HUGE, HUGE) 

negative 

negative 

(-HUGE, -HUGE) 

1 

0 

(HUGE, 0) 

-1 

0 

(-HUGE, 0) 

0 

1 

(0, HUGE) 

0 

-1 

(0, -HUGE) 
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sin(), cos(), 
sinh(), coshj) 

Synopsis 


Description 


Trigonometric and hyperbolic functions 


({include <complex.h> 
class complex 

I 

public: 

friend complex sin(complex c); 
friend complex cos(complex c); 
friend complex sinh(complex c); 
friend complex cosh(complex c); 

) ; 


The following list describes the trigonometric and hyperbolic functions 
defined for class complex. In these descriptions, c and z are of 
type complex. 

z = sin(c) 

returns the sine of c. 
z = cos ( c ) 

returns the cosine of c. 
z = sinh(c) 

returns the hyperbolic sine of c. 
z = cosh(c) 

returns the hyperbolic cosine of c. 


Returns In all overflow cases, errno is set to erange. 
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sin(), cos(), Trigonometric and hyperbolic functions 

sinh(), coshj) 

(continued) 


s in ( c ) and cos ( c ) return (0,0) if the real part of c causes 
overflow. If the imaginary part of c causes an overflow, s i n ( c ) and 
cos ( c ) return values according to the following tables. HUGE 
corresponds to the largest representable double. 


cos ( real ( c ) ) 

sin( real ( c ) ) 

cos ( c ) returns 

positive 

positive 

(HUGE, -HUGE) 

positive 

negative 

(HUGE, HUGE) 

negative 

positive 

(-HUGE, -HUGE) 

negative 

negative 

(-HUGE, HUGE) 

1 

0 

(HUGE, 0) 

-1 

0 

(-HUGE, 0) 

0 

1 

(0, -HUGE) 

0 

-1 

(0, HUGE) 

sin( real ( c ) ) 

cos ( real ( c ) ) 

sin(c) returns 

positive 

positive 

(HUGE, HUGE) 

positive 

negative 

(HUGE, -HUGE) 

negative 

positive 

(-HUGE, HUGE) 

negative 

negative 

(-HUGE, -HUGE) 

1 

0 

(HUGE, 0) 

-1 

0 

(-HUGE, 0) 

0 

1 

(0, HUGE) 

0 

-1 

(0, -HUGE) 
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sin(), cos(), Trigonometric and hyperbolic functions 

sinh(), cosh() 

( continued ) 


s inh ( c ) and cosh ( c ) return (0,0) if the imaginary part of c 
causes overflow. If the real part of c causes an overflow, sinh ( c ) and 
cosh ( c ) return values according to the following table. 


cosh(c) and sinh(c) 
cos ( imag( c ) ) sin( imag( c ) ) both return 


positive 

positive 

(HUGE, HUGE) 

positive 

negative 

(HUGE, -HUGE) 

negative 

positive 

(-HUGE, HUGE) 

negative 

negative 

(-HUGE, -HUGE) 

1 

0 

(HUGE, 0) 

-1 

0 

(-HUGE, 0) 

0 

1 

(0, HUGE) 

0 

-1 

(0, -HUGE) 
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Complex Operators for the C+ + complex library 

Operators 

Synopsis # include <complex.h> 


class complex 

{ 

public: 

friend complex operator +( complex 
friend complex operator -(complex 
friend complex operator -(complex 
friend complex operator *( complex 
friend complex operator /(complex 
friend complex operator /(complex 
friend int operator ==( complex c, 
friend int operator !={complex c, 
void operator +=( complex c); 
void operator -=(complex c); 
void operator *=(complex c ) ; 
void operator /=( complex c ) ; 
void operator /=(double d); 


c, complex b) ; 
c) ; 

c, complex b) ; 
c, complex b ) ; 
c, complex b) ; 
c, double d) ; 
complex b) ; 
complex b) ; 


}; 


Description The -, /, and /- operators are overloaded for complex numbers. The 
following list describes the function of each operator, in the order of 
precedence. In these descriptions, c and b are of type complex, and d 
is of type double. 

-c 

is the arithmetic negation of c. 
c * b 

is the arithmetic product of c and b. 
c / b 

is the arithmetic quotient of c and b. 
c / d 

is the arithmetic quotient of c and d. 
c + b 

is the arithmetic sum of c and b. 
c - b 

is the arithmetic difference of c and b. 
c == b 

is nonzero if c is equal to b; otherwise, it is zero. 
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Complex 

Operators 

(continued) 


► Caution 


Operators for the C+ + complex library 


c ! = b 

is nonzero if c is not equal to b; otherwise, it is zero, 
c += b 

assigns to c the arithmetic sum of itself and b. 
c -= b 

assigns to c the arithmetic difference of itself and b. 
c *= b 

assigns to c the arithmetic product of c and b. 
c /= b 

assigns to c the arithmetic quotient of c and b. 
c /= d 

assigns to y the arithmetic quotient of c and d. 

The assignment operators do not yield a value that can be used in an 
expression. 

For example, the following construction is not valid: 
complex a, b, c; 


a = (b += c) ; 

▲ 
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Complex Operators for the C+ + complex library 

Operators 

(i continued ) 

Example § include <complex.h> 
int main(void) 

I 

complex x; 

complex y( 10.0,20.0) ; 
complex z( 30. 0,40.0) ; 
double d; 

x = y + z ; 

cout << "x is " << x << endl; 

x = y*y; // Get y squared 

cout << y « " squared is " << x << endl; 

if (x == y*y) 

cout << "Equality operator works" << endl; 
d = real(y) ; 

printf ("real(y) == Kg\n", d); 


return 0; 
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<<j >> Complex I/O insertion and extraction operators 

Synopsis | include <complex.h> 

ostreamg operator <<(ostream6 os, complex c); 
istreamg operator >>(istreamS is, complexg c); 

Description The following operators provide insertion and extraction capabilities for 
complex numbers. 

ostreamS operator <<(ostream£ os, complex c); 

writes a complex number c to the output stream os. The output is 
formatted as follows: 

(real-part , imaginary-part) 

Both parts are formatted as doubles. The formatting is controlled by 
flags associated with the stream. For more information, see the 
description of enum format-state and of 
ostream: : operator <<(double) in the description of 
class ostream later in this chapter. 

istreamg operator >>( istreamg is, complexg c); 
reads a formatted complex number from is into c. The i stream 
should contain the complex number to be read in one of these 
formats: 

(real-part, imaginary-part) 

( real-part ) 

Both parts would be formatted as doubles. The formatting is 
controlled by flags associated with the stream. For more information, 
see the description of enum format— state and of 
istream: : operator >>(double) in the description of 
class istream later in this chapter. 

Remember the following when performing complex I/O: 

□ you must use the parentheses and comma for input 

□ you can use white space in your input but it is not significant. 

If your input variable represents a real number such as 5e-2 or (502), 
the > > operator interprets it as a complex number with an imaginary 
part of 0. 
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<<, >> 
(continued) 

Returns 


Examples 


Complex I/O insertion and extraction operators 


If the istream does not contain a properly formatted complex number, 
operator >> sets the ios : : f ailbit bit in the stream’s I/O state. 

// The following code writes the string 
// "This is a complex: (3.4,2. 1)" to cout. 

complex c( 3. 4 , 2 . 1 ) ; 

cout << "This is a complex: " << c << endl; 


// If cin contains (1.2, 3. 4), then the following code 
// reads that value into c. 

complex c; 
cin >> c; 


See Also class istream, class ostream, enum format-state 
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Performing C++ I/O 

C+ + implements I/O using streams. A stream is an ordered sequence of 
characters. Streams allow you to read from and write to different objects 
without dealing with the particular characteristics of each object. In 
C++, you are reading from or writing to either a file or an area of 
memory. 

Streams work the same way with both files and areas of memory. The 
I/O classes in C+ + convert typed objects into sequences of characters 
and provide functions that you can use to manipulate streams. You can 
extend streams to handle your own data types by declaring special 
functions, and by asking the stream code for areas to store your own 
formatting information. 

The following sections describe C+ + I/O in more detail. Specifically, 
these sections discuss: 

□ the stream classes provided by the SAS/C C+ + libraries, how these 
streams are related, and the predefined streams available to your 
program 

□ creating new streams 

□ inserting and extracting characters 

□ frequently used stream class member functions 

□ using get and put pointers 

□ using formatted C+ + I/O 

□ using I/O state flags (status flags). 

If you need additional information on C+ + I/O, refer to your C+ + 
programming manual. 

Note: The SAS/C C+ + streams library is fully compatible with the 
AT&T Release 2 streams library. 

The Stream All streams are based on class ios. This class defines the 
Class Hierarchy characteristics common to all streams. These characteristics include status 
and error flags, open modes (read, write, append, etc.), and formatting 
flags for formatted I/O. class ios also provides the ability to “tie” the 
stream to another stream. This ability allows you to make sure that all 
buffered output is flushed whenever another stream is used. For example, 
you might want all output to be flushed whenever you prompt the user 
for input. (For more information, see the description of the tie ( ) 
function in “Frequently Used Stream Class Member Functions,” later in 
this chapter.) 
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class ios has three derived classes: istream, ostream, and 
iostream. 

□ class istream is the root base for those classes that do only input. 
It includes all the functions to perform formatted input on built-in 
C+ + types, functions that perform unformatted input, and functions 
that allow moving the file position pointer. 

□ class ostream is the root base for those classes that do only 
output. It includes all the functions to perform formatted output on 
built-in C+ + types, functions that perform unformatted output, and 
functions that allow moving the file position pointer. 

□ class Iostream is simply the combination of an istream and an 
ostream. It includes all the operations of both subclasses. 

class iostream adds only constructors, not new functions. 

Nothing in classes ios, istream, ostream, or iostream determines 
where the data are read from or are written to. That is determined by 
which buffering class is associated with the stream. 

All buffering classes are based on class streambuf . This class 
controls the flushing of a full output buffer or the refilling of an empty 
input buffer. This includes the full knowledge of where the input comes 
from or where the output goes to. 

class streambuf has three derived classes: f ilebuf, stdiobuf, 
and strstreambuf . 

□ class filebuf implements buffering for disk files. 

□ class stdiobuf is like class filebuf, but it coordinates its 
buffering with the standard C library buffering. You should use 
stdiobuf in the place of filebuf if you intend to call any of the 
standard C library I/O functions. 

□ class strstreambuf implements buffering of I/O to memory, 
class strstreambuf really does not do any buffering, since the 
I/O is dealing with memory buffers anyway, but it serves as a 
placeholder in the streams hierarchy when dealing with this kind of 
I/O. You would use I/O to memory if you wanted to format C+ + data 
types, but not store the result in a file. The analogy in the C library is 
using the sprintf function. 



The C+ + library defines a suite of classes with hybrid names for each 
meaningful combination of the subclasses of class ios and the 
subclasses of class streambuf. Unless you are extending the C+ + 
I/O library, you will always use one of these names for any I/O classes 
that you declare. The naming conventions used are as follows: 

[i | o][f | stdio | str]stream 
where 

i indicates an input-only stream 
o indicates an output-only stream 
f indicates a stream that performs I/O to a file 
stdio indicates a stream that performs I/O to a file and coordinates 
with the C I/O library 

str indicates a stream that performs I/O to memory 

For example, if you want to read formatted input from an area of 
memory, you would want to initialize an istrstream object. If you 
want to write formatted or unformatted data to a file, and your program 
does not use C I/O, you would want to initialize an of stream object. If 
you want to read and write data to a file, and your program does not use 
C I/O, you would use an f stream object (which does not have an 
i or o prefix). 

Figure 8.1 shows the inheritance relationships between the various 
classes. 

Every C+ + program begins execution with four defined streams: 

cin is an is tr earn object that reads input from the same place as 
stdin. 

cout isanostream object that writes output to the same place as 
stdout. 

cerr is an ostream object that writes output to the same place as 
stderr. 

clog is an ostream object that also writes output to the same place as 
stderr. The clog object can be more highly buffered than 
cerr. 

To use these streams, you must include the header file ios tr earn. h. 

You can create additional streams as described in the next section, 
“Creating Streams.” 
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Figure 8.1 

Relationship between 
Stream Classes 


Creating Streams 


Inserting and 
Extracting 
Characters 



You create instances of stream objects like you do any other C+ + 
objects: use the new operator. Each stream class has constructors that 
allow you to initialize the stream. See the description of each individual 
class for more information on which constructors are supported for that 
class. 

An output stream is an object into which you can insert characters. The 
insertion operator is <<. For example, the following statement sends 
(inserts) the character x to the output stream object cout: 


cout << 'x' ; 









An input stream is an object from which you can extract characters. 
The extraction operator is >>. For example, the following expression 
(where ch has type char) gets a single character from the input stream 
cin and stores it in ch. 

cin >> ch; 

You can also insert or extract data types other than character. For 
example, the following statements insert the characters 1,2, and 3 into 
the stream cout, and extract characters from cin, interpret them as an 
integer, and assign the result to i : 


int i = 123; 

cout << i; // insert 1, 2, and 3 into cout 

cin >> i; // extract characters, interpret them as an integer, 
// assign result to i 

You can overload the insertion and extraction operators for user- 
defined types. For example, the following statements define an insertion 
operator for a user-defined fraction class. This operator can be used ^ 
in the same way as the insertion operator defined for the standard 
classes. 


class fraction 


int numer; // numerator 

unsigned denom; //denominator 

friend ostreamS operator <<(ostream£ os, fractions f) 


// 

// 

// 

// 

// 

// 


This overloaded operator << applies to an ostream 
object like cout and a fraction object. 

It inserts the fraction object into the ostream 
object by first inserting the fraction's numerator 
then inserting the slash and character, and finally 
inserting the fraction's denominator. 


return os << f. numer << '/' << f. denom; 
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Frequently Used 
Stream Class 
Member 
Functions 


In addition to providing the insertion and extraction operators, the 
stream classes define a number of member functions that can be more 
convenient than using the insertion and extraction operators. All of these 
functions are discussed in the class descriptions later in this chapter. The 
following list briefly describes a few of the most useful member functions. 

get( ) and getline( ) 

allows extraction of characters from a stream until a delimiter (by 
default \ n) is encountered, possibly with a limit to the number of 
characters to be extracted. The get( ) and getline( ) functions 
behave similarly, except that getline( ) extracts the final delimiter 
and get ( ) does not. 
read( ) 

extracts a fixed number of characters from a stream. read( ) is 
intended for use with binary data, whereas get( ) and getline( ) 
are usually more appropriate with text data. 
putback( ) 

allows a character extracted from a stream to be inserted back into the 
stream, so that it will be extracted again the next time a character is 
required from the stream, 
write ( ) 

inserts a number of characters into a stream. The null character is 
treated as any other character. This function is suitable for inserting 
binary data. 
flush( ) 

immediately transmits any buffered characters. For a stream 
associated with a terminal file, this function sends any buffered 
characters to the terminal. For a non-terminal file, calling f lush( ) 
may not cause any characters to be immediately written, depending on 
the characteristics of the file, 
tie ( ) 

ties one stream to another stream, so that whenever the first file’s 
buffer is full or needs to be refilled, the tied file’s buffer is flushed. 

The cin stream is automatically tied to cout, which means that 
cout's buffer is flushed before characters are extracted from cin. If, 
as is usually the case, cin and cout are both terminal files, this 
assures that you see any buffered output messages before having to 
enter a response. Similarly, the cerr stream is tied to cout, so that 
if an error message is generated to cerr, any buffered output 
characters are written first. 
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Using Get And 
Put Pointers 


Figure 8.2 
Illustration of Get and 
Put Pointers 


seekg( ) and seekp( ) 

reposition a stream for input and output, respectively. 
tellg( ) and tellp( ) 

determine the read or write position for a stream. As with the seeking 
functions, the results of these functions are system-dependent. 

C+ + stream I/O uses the concepts of the get pointer and the put pointer. 
The get pointer for a stream indicates the position in the stream from 
which characters are extracted. Similarly, the put pointer for a stream 
indicates the position in the stream where characters are inserted. Using 
the insertion or extraction operator on a stream moves the appropriate 
pointer. 

You can use member functions of the various stream classes to move 
the get or put pointer without extracting or inserting characters. For 
example, the fstream: :seekoff( ) function moves the get and put 
pointers for an fstream. 

The exact behavior of the get and put pointers for a stream depends on 
the type of stream object. For example, for fstream objects, the get and 
put pointers are tied together. That is, any operation that moves one 
pointer always moves the other. For strstream objects, the pointers 
are independent. That is, either pointer can be moved without affecting 
the other. 

The get and put pointers refer to positions between the characters of 
the stream, not the positions of the characters. For example, Figure 8.2 
shows possible positions of the get and put pointers for a stream. 

vocabulary 



get put 

pointer pointer 


In Figure 8.1, the next character extracted from the stream is c and the 
next character inserted into the stream replaces the r. 

Note: These pointers are abstract pointers. They refer to positions in 
the sequence of characters associated with the stream, but they are not 
C+ + pointers that address specific memory locations. 
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Using Formatted You may need to format output in C+ + similar to the way the printf 
C+ + I/O function allows you to format output in C programs. For example, your 
application may need to output an unsigned intasa decimal number 
or as a hexadecimal number. In C++, you can perform formatted I/O 
using functions or manipulators. 

Using Functions 

class ios provides several formatting functions, and all stream classes 
inherit these functions. The member function setf ( ) allows you to set 
flags that control how I/O is formatted. For example, the following 
expression sets the default for the stream cout to hexadecimal, so that 
integral values written to cout are written in hexadecimal: 

cout. setf (ios: :hex, ios: :basefield) ; 

class ios provides three additional formatting functions: 
width( ) 

sets the number of characters to display. 
fill() 

defines the fill character when there are fewer characters to insert 
than the width. 
precision( ) 

sets the number of significant digits to write for floating-point values. 

Using Manipulators 

Using the setf( ), width( ), and similar functions is convenient if your 
application uses the same specifications for a large number of inserted 
items. If the formatting frequently changes, it is more convenient to use a 
manipulator. A manipulator is an object that is an operand to the << or 
>> operator and modifies the state of the stream, instead of inserting or 
extracting any data. 

For example, you can use the hex or dec manipulators to print 
integral values in hexadecimal or decimal. The following cout statement 
writes the value of i in decimal and the value of x [ i ] in hexadecimal: 

cout << "i = " << dec << i << ",x[i] = " << hex << x[i]; 

class ios also defines the following manipulators: 
ws skips white space on input, 
flush flushes a stream’s buffer. 



628 Chapter 8 


endl inserts a newline character and then flushes the stream’s buffer, 
ends inserts an end-of-string character (NO). 

You can also create user-defined manipulators. Refer to the 
iomanip.h header file for examples or to C+ + Programming Language, 
Second Edition for a discussion of user-defined manipulators. The 
directory sc : examples /streams contains an example of creating 
user-defined manipulators. 


Determining the 
Status of An I/O 
Stream (state 
flags) 


Associated with each stream is a set of flags indicating the I/O state of 
the stream. For example, the flag ios: : eof bit indicates that no more 
characters can be extracted from a stream and the flag ios: rfailbit 
indicates that a previous request failed. The I/O state flags can be tested 
by member functions. For example, cin. eof ( ) tests whether more 
characters can be extracted from the standard input stream. The I/O state 
flags can be manipulated by using the clear ( ) member function; for 
example, cout . clear ( 0 ) clears all the I/O state flags for the stream 
cout. 

For convenience, the ! operator or conversion to void* allows concise 
testing of a stream for any error. These operators allow you to use 
statements such as the following, which writes the results of the function 
nextline to the standard output stream until an error occurs: 


while(cout) 

cout << nextline ( ) ; 

Because an insertion or extraction always produces a stream object as its 
result, the preceding code can be abbreviated as follows: 


while(cout << nextline()); 

This form makes it more obvious that the loop might not terminate at all. 
Attempting to extract from a stream from which no more characters can 
be taken is considered a failure. Therefore, you can use a loop such as 
the following to extract and process items from a stream until the stream 
is exhausted: 


while(cin >> datum) 
process (datum) ; 
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Compatibility 
With AT&T 
(stream. h) 


The streams library is fully compatible with the AT&T Release 2 streams 
library. 

The C+ + streams library was redefined after the first release and the 
Release 2 version is somewhat incompatible with Release 1. (Release 1 is 
described in Stroustrop’s book, The C+ + Programming Language, First 
Edition.) SAS/C C+ + implements the old Release 1 streams library in 
the header file stream. h. However, this usage is obsolete. The 
functions, constants, and types defined in the stream. h header file may 
not be supported by future versions of the SAS/C C+ + I/O library. 

All of the functions declared in this header file share an internal 
static data area and return a pointer to this data area. Each call to any 
of these functions overwrites this data area. 

The stream. h header file contains the following: 

char* form(char *format, . . .) 

provides print f style formatting of character strings. The format 
string is the same as the format string for the C printf function. 

(See the description of printf in Chapter 7 for more information.) 
The number and type of the arguments following the format 
argument are controlled by the format string. 


char* 

oct ( long 

value , 

int 

size = 0 ) 

char* 

hex ( long 

value , 

int 

size = 0) 

char* 

dec ( long 

value , 

int 

size = 0 ) 

char* 

chr ( long 

value , 

int 

size = 0 ) 

char* 

str ( char 

♦value , 

r int 

size = 0 


format value into a string and return a pointer to the string. The 
following list describes each function in more detail: 
oct( ) formats value as an octal number using the digits 0-7. 
hex ( ) formats value as a hexadecimal number using the digits 0-9 
and uppercase A-F. 

dec ( ) formats value as a decimal number using the digits 0-9. 
chr ( ) formats value as a character. 
str( ) formats value as a string. 

If size is zero, the returned string is exactly as long as needed to 
represent the value of 1 . Otherwise, if size is less than the length of 
the converted value, the converted value is truncated on the right. If 
size is greater than the length of the converted value, spaces are 
added to the left of the converted value. 
istreamS WS( istreamS i) 
void eatwhite ( istreamS i) 

move the get pointer for i past any whitespace. If the current 
character of i is not a whitespace character, these functions do 



nothing. A whitespace character is any character for which the macro 
is space returns true. See Chapter 7 for a description of isspace. 
const int input = ios::in 
const int output = ios::out 
const int append = ios::app 
const int atend = ios::ate 
const int _good = ios::goodbit 
const int —bad = ios::badbit 
const int —fail = ios::failbit 
const int _ eof = ios::eofbit 

are constants that are passed to or are returned from functions of the 
I/O library. These names are only provided for compatibility with old 
programs; the new i o s : : style names should be used in new 
programs. See the description of enum io_ state, later in this 
chapter, for details on each constant, 
typedef ios : : io_ state state— value 

provides the old name ( state— value ) for what is now defined as 
ios : : io_ state. See the description of enum io_ state, later in 
this chapter, for details on ios : : io_ state. 

Note: ANSI Committee X3J16 is currently working on an official 
standard for C++, including the streams library. As this work proceeds, 
there will probably be additional changes in the streams library. Some of 
these changes may cause existing programs to fail. It is therefore 
recommended that C+ + streams applications be kept relatively simple, 
to lessen the chance of problems caused by redefinition of the more 
obscure parts of the library. It is especially recommended that you avoid 
deriving from the streambuf classes because this interface is 
infrequently used and is expected to be volatile. 


I/O Class Descriptions 

The class descriptions for the C+ + I/O library are divided into three 
parts: 

□ stream classes (such as i stream and os tr earn) 

□ buffer classes (such as filebuf and streambuf) 

□ manipulators (class IOMANIP). 

Most C+ + programmers need to understand only the stream classes. 
However, if you are doing more advanced programming, such as creating 
your own streams, you may want to also read the descriptions of the 
buffer and manipulator classes. 
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Stream Class 
Descriptions 


The protected interfaces in each of the classes have been implemented 
in accordance with AT&T Version Release 3.0, but are beyond the scope 
of this book to describe. For information on the protected interface for 
these classes, refer to your C+ + book (such as the C+ + Language 
System Release 3.0 Library Manual). 

Note: It is not recommended that you use the protected member 
functions in your applications. This interface is volatile and is quite likely 
to change when the ANSI committee generates a C+ + standard. Using 
the protected interface in your applications makes them much more likely 
to be quickly obsolescent. 

This section provides descriptions of the stream classes, such as 
iostream and str stream. As noted previously, the protected interface 
to these functions is not documented in the descriptions that follow. Each 
class (or occasionally, a set of related classes) is listed alphabetically. All 
class descriptions include the following information: 

□ a synopsis of the class 

□ a brief description of the purpose and structure of the class 

□ a discussion of parent classes 

□ a detailed description of the members of the class 

□ examples of using some of the members, if appropriate 

□ a See Also section that points you to related classes. 

In addition, some class descriptions contain other sections, as appropriate 
for the class. 

The following classes are described in this section: 


istream 

ostream 

iostream 


f stream 
if stream 
of stream 


strstream 
istr stream 
ostr stream 


ios 

stdiostream 

streampos 


The class ios description is divided into several sections. One 
section describes the basic stream-manipulation functions. The other 
sections deal with the enumerations provided by class ios and the 
functions that manipulate these enumerations. Examples of the 
enumerations include the format flags, the I/O state flags, the open mode 
flags, and the seek_dir flags. 

Note: The term character in the following class and function 
descriptions refers to either a char, a signed char, or an 
unsigned char. 
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class fstream 

Synopsis 


Description 
Parent Class 

Constructors 


Destructors 


Provide formatted file I/O 

{(include <fstream.h> 

class fstream : public iostream 

I 

public: 

fstream( ) ; 

fstream! const char *name, int mode); 
virtual ~fstream(); 

void open(const char *name, int mode); 
void close! ) ; 

void setbuf(char *p f size_t len); 
f ilebuf * rdbuf ( ) ; 


class fstream implements an input/output stream whose destination 
is a file. The streambuf associated with the I/O operations is a 
f ilebuf (instead of a strstreambuf or stdiobuf). 

class fstream inherits characteristics from class iostream, 
which inherits characteristics from class ios. See the descriptions of 
these parent classes for the details on functions and operators that are 
inherited. 

There are two sets of constructors for class fstream, as follows: 

fstream: :fstream( ) ; 

creates an unopened stream of the appropriate type, 
fstream: : fstream! const char *name, int mode); 
creates a stream of the appropriate type, named name, using the 
specified mode. 

See the description of enum open_mode, later in this chapter, for 
information on the available modes. If the open fails, the stream’s 
status is reflected in its I/O state flags. See the description of 
enum io_state, later in this chapter, for information on the I/O 
state flags. 

class fstream has one destructor: 

virtual fstream: :~f stream! ) ; 
close the stream, if opened. 
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Class f Stream Provide formatted file I/O 
(continued) 

Member Functions The following descriptions give the purpose and return type of the 
member functions, as well as any other appropriate information. 

void f stream: : open( const char *name, int mode); 
opens the named file using the specified mode. There is no default 
mode bit set. See the description of enum open_jmode, later in this 
chapter, for information on the available open modes. 

This function does not have a return value. If an error occurs 
during the open, the ios : : f a i lb it bit is set in the stream’s I/O 
state. For example, the file may already exist, or the call to 
rdbuf ( ) ->open( ) may fail, 
void f stream: : close () ; 

closes the connection between the appropriate object and its associated 
file. Unless an error occurs, all bits in the object’s I/O state are set to 
zero. The close could fail if the call to rdbuf ( )->close( ) fails. 

This function has no return value, 
void f stream: : setbuf ( char *p, size_t len); 

calls f ilebuf : : setbuf ( p , len ) . This function has no return 
value. 

filebuf* f stream: : rdbuf () ; 

returns a pointer to the filebuf associated with the stream. 

Example uinclude <fstream.h> 

// Example using an f stream (Input/Output File-based stream) 
int main(void) 

I 

// Declare an fstream object called "mystream" and initialize 
// it to perform I/O to the file "myiofile.dat" 
fstream mystream( "myiofile.dat" , ios: :inlios: :out) ; 

// Declare an unopened fstream object called "mystream2" 
fstream mystream2; 

// Declare a pointer to an fstream object 
fstream *stream_p; 


int i ; 
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class fstream 

( continued ) 


Provide formatted file I/O 


if ( Imystream) 

I 

cout << "Error opening file V'myiof ile.datN" ! " << endl; 
return 20; 

} 

// Read an integer from the file attached to "mystream" 
mystream >> i; 

if ( Imystream) cout << "Read from V'myiofile.datV' failed" << endl; 
else cout << "Read " << i << " from \"myiof ile.datN"" << endl; 

i = i + 1 ; // Add one to the integer 

mystream. seekp(0,ios: :beg) ; // Seek back to beginning of file 

mystream « i; // Write the integer back 

if ( Imystream) cout « "Write to V'myiof ile.datN" failed" << endl; 
else cout << "Wrote " « i << " to V'myiof ile.datN"" << endl; 

// Initialize the unopened "mystream2" stream to perform I/O to 
// the file "myiofile2.dat" 

mystream2.open( "myiofile2.dat" , ios: : app I ios: : in I ios: :out) ; 

if ( !mystream2) 

{ 

cout << "Error opening file V'myiof ile2 . dat\" ! " << endl; 
return 20; 


// Read an integer from "myiofile2.dat" 
mystream2 » i; 

if ( !mystream2 ) cout << "Read from myiofile2.dat failed" << endl; 
else cout << "Read " << i « " from myiofile2.dat" << endl; 

// Write the new integer. Note that this will APPEND the new 
// integer to the old file, not replace the old file, since 
// we did not seek to the beginning of the file before writing. 
// Put a blank in to seperate the old integer from the new one. 
i = i + 1; 
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Class f Stream Provide formatted file I/O 
( continued ) 

mystream2 << " " << i; 

if ( !mystream2) cout << "Write to myiofile2.dat failed" << endl; 
else cout << "Appended " « i « " to myiofile2.dat" « endl; 

// Allocate a new fstream using "new" and use it to perform I/O to 
// the file "myiofile3.dat" 

stream_p = new f stream( "myiof ile3 .dat" , ios: : in I ios: :out) ; 
if(!stream_p II !*stream_p) 

I 

cout << "Error opening file Vmyiof ile3 .dat\" ! " << endl; 
return 20; 

) 

*stream_p >> i; 

if ( !*stream_p) cout << "Read frommyiofile3.dat failed" << endl; 
else cout << "Read " « i << " from myiofile3.dat" << endl; 

i = i + 1 ; 

stream_p->seekp(0, ios::beg); // Rewrite this one, not append 
*stream_p << i; 

if ( !*stream_p) cout << "Write to file myiofile3.dat failed" << endl 
else cout << "Wrote " << i << " to myiofile3.dat" << endl; 

// Free the object just allocated. This will call the destructor 
// for the stream and therefore close the file, 
delete stream_p; 

// Destructors for the other streams will automatically be called, 
return 0; 

) 

See Also class filebuf, class ifstream, class ofstream 
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class ifstream 

Synopsis 


Description 
Parent Class 

Constructors 


Provide formatted file I/O 

((include <fstream.h> 
class ifstream : public istream 
( 

public: 

if stream ( ) ; 

if stream( const char *name, int mode = ios:: in); 
virtual ~if stream! ) ; 

void open( const char *name, int mode = ios:: in); 
void close! ) ; 

void setbuf(char *p, size_t len); 
f ilebuf * rdbuf ( ) ; 

); 


class ifstream is an input-only stream whose input source is a file. 
The streambuf associated with the I/O operations is a f ilebuf 
(instead of a strstreambuf or stdiobuf). 

class ifstream inherits characteristics from class istream, 
which inherits characteristics from class ios. See the descriptions of 
these parent classes for the details on functions and operators that are 
inherited. 

There are two sets of constructors for class ifstream, as follows: 
ifstream: :ifstream( ) ; 

creates an unopened stream of the appropriate type. You can use the 
open( ) member function to open the stream after it is created, 
if stream: : if stream! const char *name , int mode = 
ios : : in ) ; 

creates a stream of the appropriate type, named name, using the 
specified mode. The ifstream constructor behaves as if ios :: in 
was set in the mode argument, whether or not it was set by the caller. 

See the description of enum open_mode, later in this chapter, for 
information on the available modes. If the open fails, the stream’s 
status is reflected in its I/O state flags. See the description of 
enum io_state, later in this chapter, for information on the I/O 
state flags. 
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class ifstream 

(continued) 

Destructors 
Member Functions 


Example 


Provide formatted file I/O 


class ifstream has one destructor: 

virtual if stream: :~ifstream( ) ; 
closes the stream, if opened. 

The following descriptions give the purpose and return type of the 
member functions, as well as any other appropriate information. 

void if stream: : open ( const char *name, int mode = 
ios : : in ) ; 

opens the named file using the specified mode, ifstream: :open( ) 
behaves as if ios : : in was set in the mode argument, whether or not 
it was set by the caller. 

See the description of enum open_mode, later in this chapter, for 
information on the available open modes. 

This function does not have a return value. If an error occurs 
during the open, the ios : : f ailbit bit is set in the stream’s I/O 
state. For example, the call to rdbuf ( )->open( ) may fail, 
void if stream: : close () ; 

close the connection between the appropriate object and its associated 
file. Unless an error occurs, all bits in the object’s I/O state are set to 
zero. The close could fail if the call to rdbuf ( )->close( ) fails. 

This function has no return value, 
void if stream: : setbuf ( char *p, size_t len) ; 

calls f ilebuf : : setbuf (p, len) . This function has no return 
value. 

f ilebuf* if stream: : rdbuf () ; 

returns a pointer to the f ilebuf associated with the stream. 

((include <fstreara.h> 

// Example using an ifstream (Input-only File-based stream) 
int main(void) 

{ 

// Declare an ifstream object called "mystream" and initialize 
// it to read bytes from the file "myfile.dat" 
ifstream mystream( "myfile.dat" ) ; 


// Declare an unopened ifstream object called "mystream2" 
ifstream mystream2; 
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class ifstream 

(continued) 


Provide formatted file I/O 


// Declare a pointer to an ifstream object 
ifstream *stream_p; 

int i; 

if ( ! mystream) 

( 

cout << "Error opening V'myf ile.datV'! " << endl; 
return 20; 

) 


// Read an integer from the file attached to "mystream" 
mystream >> i; 

// Print the integer to the program's standard output 

cout « "The integer in the file V'myfile.datV is " << i << endl; 

// Initialize the unopened "mystream2" stream to read from 
// the file "myfile2.dat" 
mystream2.open( "myfile2.dat" ) ; 

if ( !mystream2) 

( 

cout << "Error opening V'myf ile2.dat\" ! " « endl; 
return 20; 


// Read an integer from "myfile2.dat" and print the result 
mystream2 >> i; 

cout << "The integer in the file V'myf ile2 .dat\" is " << i « endl 

// Allocate a new ifstream using "new" and use it to read from 
// the file "myfile3.dat" 
stream_p = new ifstream("myfile3.dat"); 

if(!stream_p II !*stream_p) 

f 

cout << "Error opening V'myf ile3 .dat\" ! " << endl; 
return 20; 
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Class if Stream Provide formatted file I/O 
(continued) 


*stream_p >> i; 

cout << "The integer in the file V'myf ile3 .dat\" is " << i << endl 

// Free the object just allocated. This will call the destructor 
// for the stream and therefore close the file, 
delete stream_p; 

// Destructors for the other streams will automatically be called, 
return 0; 


See Also class filebuf, class fstream, class ofstream 
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class ios Provide buffer and stream manipulation 

Synopsis fjinclude <iostream.h> 

class ios 

( 

public: 

/* See the enum format-state , enum io_state, enum open_mode */ 
/* and enum seek_dir descriptions for more definitions. */ 

ios ( streambuf *buf ) ; 
virtual ~ios( ) ; 

int width( ) ; 
int width( int w) ; 

char f i 1 1 ( ) ; 
char fill(char c) ; 

int precision( ) ; 
int precision( int i); 

static unsigned long bitalloc(); 
static int xalloc( ) ; 
long 6 iword( int i) ; 
void*6 pwordfint i); 

streambuf* rdbuf ( ) ; 

ostream* t ie ( ) ; 
ostream* tie(ostream *s); 

}; 


Description The iostream.h header file declares class ios. This class and 

classes derived from it provide an I/O interface for inserting information 
into and extracting information from streambufs. All stream classes are 
derived from class ios. This I/O interface supports both formatted 
and unformatted information. This description is devoted to those 
operations used in stream and buffer manipulation. 

Several enumerations are defined in class ios (io_state, 
open_mode, seek_dir, and the format flags). These enumerations are 
described in subsequent sections. The open_mode and seek_dir flags 
are not used directly by the functions in class ios, but they are used 
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class ios 

(continued) 

Parent Class 
Constructors 

Destructors 


Buffer and Stream 
Manipulation 
Functions 


Formatting Functions 


Provide buffer and stream manipulation 


by classes derived from it. You will not normally use class ios 
directly, but rather one of the classes derived from it. 

class ios is the parent of all the stream classes. It has no parent class. 

class ios defines one constructor: 
ios : : ios ( streambuf *buf ) ; 

sets up buf as the associated streambuf. If buf is NULL, the effect 
is undefined. 

class ios has one destructor: 

virtual ios::~ios(); 
closes the stream. 

class ios defines several functions that provide buffer and stream 
manipulation capabilities. The following list describes these functions. 

streambuf* ios : : rdbuf ( ) ; 

returns a pointer to the streambuf associated with the ios when it 
was created. 

ostream* ios::tie(); 

returns the ostream currently tied to the ios, if any; returns NULL 
otherwise. 

ostream* ios :: tie ( ostream * s ) ; 

ties s to the ios and returns the stream previously tied to this 
stream, if any; returns NULL otherwise. 

If the ios is tied to an ostream, then the ostream is flushed 
before every read or write from the ios. By default cin, cerr, and 
clog are tied to cout. 

class ios defines several functions that use and set the format flags 
and variables, class ios also provides functions you can use to define 
and manipulate your own formatting flags, plus several built-in 
manipulators that allow you to set various format flags. 

Format flag functions 

The following list describes some of the functions that use and set the 
library-supplied format flags. For information on the flags ( ), setf ( ), 
and unset f ( ) functions and the format flags, see the description of 
enum f ormat_state, later in this chapter. 
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Class iOS Provide buffer and stream manipulation 
( continued ) 


int ios : : width( ) ; 

returns an int representing the value of the current field width, 
int ios : : width( int w) ; 

sets the field width to w and returns an int representing the previous 
field width value. 

The default field width is 0. When the field width is 0, inserters 
insert only as many characters as necessary to represent the value. 
When the field width is nonzero, inserters insert at least as many 
characters as are necessary to fill the field width. The fill character is 
used to pad the value, if necessary, in this case. 

Numeric inserters do not truncate their values. Therefore, if the 
value being inserted is wider than the field width, the entire value is 
inserted, regardless of the field width overrun. The field width value is 
a minimum constraint; you cannot specify a maximum constraint on 
the number of characters to be inserted. 

The field width variable is reset to 0 after each insertion or 
extraction. In this sense, the field width serves as a parameter for 
insertions and extractions. 

You can also use the predefined manipulator, setw, to set the field 
width. 

char ios : : f ill ( ) ; 

returns a char representing the current fill character, 
char ios :: fill ( char c); 

sets the fill character to c and returns a char representing the 
previous value. The default fill character is a space. You can also set 
the fill character using the predefined manipulator, set fill, 
int ios : :precision( ) ; 

returns an int representing the current precision value, 
int ios : :precision( int i); 

sets the precision to i and returns an int representing the previous 
precision. Use this function to control the number of significant digits 
included in floating-point values. The default precision is six. You can 
also set the precision using the predefined manipulator, 
setprecision. 

User-defined format flag functions 

class ios includes four functions that you can use to define format 
flags and variables in addition to those described in the 
enum format — state description. 
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Class iOS Provide buffer and stream manipulation 
(continued) 


static unsigned long ios : : bitalloc ( ) ; 

returns an unsigned long with a single, previously unallocated, bit 
set. This allows you to create additional format flags. This function 
returns 0 if there are no more bits available. Once the bit is allocated, 
you can set it and clear it using the flags ( ) , set f ( ) , and 
unset f ( ) functions, 
static int ios : : xalloc ( ) ; 

returns an int that represents a previously unused index into an array 
of words available for use as format state variables. These state 
variables can then be used in your derived classes. 
long& ios : : iword ( int i); 

returns a reference to the ith user-defined word, i must be an index 
allocated by ios : : xalloc ( ) . 
void*S ios : : pword( int i); 

returns a reference to the ith user-defined word, i must be an index 
allocated by ios : : xalloc ( ) . pword ( ) is the same as iword ( ) 
except that its return type is different. 

Refer to the C+ + Language System Release 3.0 Library Manual for 
more information on defining and using user-defined format flags. 

Built-in manipulators 

Manipulators take an ios £, an istreamS, or an ostreamS and return 
their argument. The following built-in manipulators are useful with ios 
objects, stream has type iosS. 

stream >> dec and stream << dec 

set the conversion base for the stream to decimal (by setting the 
ios: :dec bit and clearing ios: :oct and ios: :hex). 
stream >> oct and stream << oct 

set the conversion base for the stream to octal (by setting the 
ios : : oct bit and clearing ios : : dec and ios : : hex), 
stream >> hex and stream << hex 

set the conversion base for the stream to hexadecimal (by setting the 
ios : : hex bit and clearing ios : : dec and ios : : oct). 
stream >> ws 

extracts whitespace characters, 
stream << endl 

inserts a newline character and flushes the stream. 
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stream << ends 

inserts a null (\0) character into the stream, 
stream << flush 

flushes the given o stream object. 

In addition, you can use predefined manipulators such as setfill, 
setpreclsion, setiosflags, and resetlosf lags to operate on 
ios objects. For information on predefined manipulators, see the 
description of class I OMANI P, later in this chapter. 


See Also 


class iostream, class istream, class ostream 
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enum 

format-state 

Synopsis ({include <iostream.h> 

class ios 

( 

public: 

/* See the class ios, enum io_state, enum open_mode, and */ 

/* enum seek_dir descriptions for more definitions. */ 

enum (skipws, 

left, right, internal, 
dec, oct, hex, 

showbase, showpoint, uppercase, showpos, 
scientific, fixed, 
unitbuf, stdio 
); 

static const unsigned long basefield; 
static const unsigned long adjustfield; 
static const unsigned long floatfield; 

unsigned long flags ( ) ; 

unsigned long flags(unsigned long f); 

unsigned long setf (unsigned long mask); 

unsigned long setf (unsigned long setbits, unsigned long mask); 
unsigned long unsetf (unsigned long mask); 

}; 

Description class ios (defined in the iostream.h header file) provides a format 
state, which is used by the stream classes to control formatting. The 
format state is controlled by the format flags and class ios provides 
several functions to manipulate these flags. The member functions 
flags ( ) , setf ( ) , and unsetf ( ) control the majority of formatting. 
These functions are described in the Formatting Functions section. Other 
member functions that have an effect on the format state are f i 1 1 ( ) , 
width ( ), and precision ( ). For information on these functions, see 
the description of class ios, earlier in this chapter. 
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In addition to the predefined format flags, users can create their own 
user-defined format flags. For more information, see “User-defined format 
flag functions” in the description of class ios, earlier in this chapter. 

The following list describes each format flag in detail, 
skipws 

skips whitespace on input. This flag applies only to scalar extractions. 
If skipws is not set, whitespace is not skipped. 

To protect against looping, zero-width fields are considered a bad 
format. Therefore, if the next character is whitespace and skipws is 
not set, arithmetic extractors signal an error, skipws is set by 
default, 
padding flags 

control the padding of formatted values. There are three of them: 
left left-justifies the output, 
right right-justifies the output. If padding is not specified, 
right is the default value. 

internal causes padding to occur between the sign or base 
indicator and the value. 

These padding flags are grouped together by the member 
adjustf ield. To set the fill character, use the fill( ) function. To 
control the width of formatted items, use the width ( ) function, 
conversion base flags 

control the conversion base of values, as follows: 

dec specifies decimal as the conversion base. If a conversion base 
is not specified, dec is the default value, 
oct specifies octal as the conversion base, 
hex specifies hexadecimal as the conversion base. 

These conversion base flags are grouped together by the member 
basef ield. 

Although decimal is the default conversion base for insertions (if 
none of these flags are set), the default conversion base for extractions 
follows the C+ + lexical conventions for integral constants. You can 
also use the built-in manipulators dec, oct, and hex to control the 



C+ + Library Reference 647 


class ios, 
enum 
format-state 

( continued ) 


Provide buffer and stream formatting 


conversion base. These manipulators are described in the previous 
class ios description, under “Built-in Manipulators.” 
showbase 

causes the base indicator to be shown in the output. This form of 
output follows the C+ + lexical conventions for integral constants, 
showbase is not set by default, 
showpoint 

causes the output to include any trailing zeros and decimal points 
resulting from floating-point conversion, showpoint is not set by 
default, 
uppercase 

causes uppercase letters to be used in output of base indicators and 
scientific notation. For example, an X is used instead of x in 
hexadecimal output and an E is used instead of e in scientific notation, 
uppercase is not set by default, 
showpos 

causes a + sign to be added to the decimal conversion of positive 
integers, showpos is not set by default, 
floating-point flags 

control the format of floating-point conversions, as follows: 
scientific 

causes the value to be converted using scientific notation. In this 
form, there is one digit preceding the decimal point and the 
number of digits after the decimal point is equal to the precision 
(set with the precis ion ( ) function). The default precision is six. 
An e (or E if uppercase is set) precedes the exponent, 
fixed 

causes the value to be converted to decimal notation. The precision 
of the value is controlled with the precision( ) function. The 
default precision is six. 

If neither scientific or fixed is set, the value is converted to 
one or the other format, according to the following rules: 

□ If the exponent resulting from the conversion is less than - 4 or 
greater than the precision, scientific notation is used. 

□ Otherwise, fixed notation is used. 
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Unless showpoint is set, trailing zeros are removed from the 
value, regardless of the format. A decimal point appears in the value 
only if it is followed by a digit. These flags are grouped together by 
the member floatfield. They are not set by default, 
unitbuf 

causes the stream to be flushed after an insertion, unitbuf is not set 
by default, 
stdio 

causes the standard C output files stdout and stderr to be flushed 
after an insertion, stdio is not set by default. 

The following functions can be used to turn format flags on and off. 

unsigned long ios :: flags () ; 

returns an unsigned long representing the current format flags, 
unsigned long ios :: f lags ( uns igned long f); 

sets (turns on) all the format flags specified by f , unsets all format 
flags not specified by f, and returns an unsigned long 
representing the previous flag values, 
unsigned long ios :: setf ( unsigned long mask); 
sets (turns on) only those format flags that are set in mask and 
returns an unsigned long representing the previous values of those 
flags. All other flags are left untouched. You can accomplish the same 
task by using the predefined manipulator, setiosflags. 
unsigned long ios :: setf ( unsigned long setbits, 
unsigned long mask); 

turns on or off the flags marked by mask according to the 
corresponding values specified by setbits and returns an 
unsigned long representing the previous values of the bits 
specified by mask. The Examples section provides an example of using 
this function. 

Using setf( 0 , mask) clears all the bits specified by mask. You 
can accomplish the same task by using the predefined manipulator 
resetiosf lags. 

unsigned long ios :: unset f ( uns igned long mask); 
clears the format flags specified by mask and returns an 
unsigned long representing the previous flag values. 
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Examples The setf ( ) function is used to change format flags. For example, if you 
want to change the conversion base in an ios object called s, you could 
use the following expression: 

s.setf (ios: :hex, ios: :basef ield) 

In this example, ios: :basefield represents the conversion base bits 
you want to change and ios : :hex is the new value. 

To set a flag that is not part of a field, use setf ( ) with a single 
argument, as in the following example, which sets the skipws flag: 

s.setf (ios: : skipws) 

To clear the skipws flag, use unsetf ( ): 
s.unsetf (ios: :skipws) 

As another example of using setf ( ), suppose you want to clear in 
your ios object s all the bits specified by the variable clearbits. You 
could use the following expression to accomplish this: 


s.setf(0, clearbits) 
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Description 
I/O State Flags 


Provide stream I/O state 


((include <iostream.h> 

class ios 

( 

public: 

enum io_state (goodbit = 0, 
eofbit, 
failbit, 
badbit 
}; 


/* See the class ios, enum format-state, enum open_mode, and */ 
/* enum seek— dir descriptions for more definitions. */ 

int rdstate( ) ; 
int eof ( ) ; 
int fail ( ) ; 
int bad( ) ; 
int good ( ) ; 

void clear(int i = 0) ; 

operator void*(); 
int operator ! { ) ; 


class ios (defined in the iostream.h header file) defines 
io_state flags that represent the internal state of an ios object . Each 
flag has a value that can be set or reset independently for an i o s object, 
goodbit is not a flag, but rather a symbolic name for the condition in 
which no flags are set. The functions such as rdstate( ) and eof ( ) 
use and manipulate the I/O state flags. 

A stream is in an unusual state (error or EOF) if any of the I/O state 
flags are set for the stream. If none of the flags are set, the stream is in 
the normal (non-error) state. The meaning of the io_state enumerators 
are as follows: 

goodbit is not a flag. It is a symbolic name for the condition in which 
no flags are set. 

eofbit indicates the end of file has been encountered. If the stream 
is repositioned after eofbit is set, the bit is cleared. 



C+ + Library Reference 651 


class ios, 
enum io state 

( continued ) 


I/O State Functions 


Provide stream I/O state 


f a i lb it indicates an error other than an I/O error, such as an error 
in formatting. Once the failbit bit is cleared, I/O can 
usually continue, failbit is also set if an operator or 
member function fails because no more characters can be 
extracted. 

badbit indicates an I/O operation failed. It is usually ill-advised to 
continue I/O operations after this bit is set. 

class ios also provides several functions that use or manipulate the 
I/O state flags. In addition to the I/O state functions, class ios also 
defines two operators that allow you to check the I/O state of an ios 
object. The following functions use and manipulate the values of the I/O 
state flags. 

int ios : : rdstate ( ) ; 

returns the current I/O state, 
int ios : : eof ( ) ; 

returns the value of eofbit if eofbit is set; otherwise, returns 0. 
int ios : : f ail ( ) ; 

returns the value of failbit if failbit is set; otherwise, returns 
0. 

int ios : : bad ( ) ; 

returns the value of badbit if badbit is set; otherwise, returns 0. 
int ios : : good ( ) ; 

returns a nonzero value if no bits are set in the stream’s I/O state; 
otherwise, returns 0. 
void ios :: clear ( int i = 0); 

sets the stream’s I/O state to i. The default value for i is 0. The 
clear ( ) function has no return value. 

The following two operators are useful when checking the I/O state of an 
ios object. 

ios :: operator void*(); 

converts an ios object to a pointer. If no bits are set in the stream’s 
I/O state, this operator returns a non-NULL pointer value. If 
failbit or badbit is set, the operator returns 0. 
int ios :: operator !(); 

converts an ios object to 0 if no bits are set in the stream’s I/O state, 
or to a nonzero value if any bits are set in the stream’s I/O state. 
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open_mode 

Synopsis ((include <iostream.h> 

class ios 

( 

public: 

/* See the class ios, enum format-state, enum io_state, */ 
/* and enum seek_dir descriptions for more definitions. */ 

enum open_mode (in, out, ate, app, trunc, nocreate, 
noreplace, binary 
); 


Description The open_mode enumeration is defined in iostream.h. This 

enumeration defines a number of flags that can be used when creating or 
opening a stream to specify attributes of the stream. You can specify 
several attributes simultaneously by using the OR operator to combine 
them. For example, to specify both the out and binary flags, use 
ios : : out I ios : : binary. Only the ios : : ate and ios : : app flags 
are meaningful for string streams, such as strstream objects. See the 
description of class strstream, class istrstream, and 
class ostrstream for information on how these flags are used with 
these classes. 

The following list describes the meaning of the open_mode flags for 
the file-oriented stream classes: 

in means access the file for input. 

out means access the file for output. If the file already exists, it 
is truncated unless one of ios : : in, ios : : ate, or 
ios : : app is also specified. 

ate means to position the put pointer to the end of the file 
when the file is opened. 

app means to access the file in append mode. In append mode, 
each output operation to the file causes the put pointer to 
be positioned to the end of the file before writing, 
trunc means to truncate the file (making it empty) when it is 
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opened, ios : : trunc has no effect if the file does not yet 
exist. 


nocreate means the open fails if the file to be opened does not exist, 
noreplace means the open fails if the file already exists. 


binary means to access the file in binary mode. If ios: :binary 
is not specified, the file is accessed in text mode. See the 
description of the f open function in Chapter 7 for 
information on accessing a file in text mode (Mode A) and 
binary mode (Mode B). 



654 Chapter 8 


class ios, 
enum seek_dir 

Synopsis 


Description 


Provide buffer and stream seeking 


jfinclude <iostream.h> 
class ios 

I 

public: 

/* See the class ios, enum format-state, enum open_mode, */ 
/* and enum open_mode descriptions for more definitions. */ 

enum seek_dir (beg, cur, end); 

}; 


When you perform a seek on a stream, you must specify the starting 
point for the seek, class ios (defined in the iostream.h header file) 
provides the seek_dir flags to control seeking. The following list 
describes these flags: 

beg means the seek is relative to the beginning of the stream, 
cur means the seek is relative to the current position of the stream, 
means the seek is relative to the end of the stream. 


end 
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Synopsis 


Description 

Parent Class 
Constructors 

See Also 


Provide bidirectional stream 

#include <iostream.h> 

class iostream : public ostream, 
public istream 

{ 

public: 

iostream(streambuf *buf); 


The iostream. h header file also provides class iostream, which is 
both an istream and an ostream. class iostream includes all 
the operations of both subclasses. It adds only a constructor of its own. 
You will not normally use class iostream directly, but rather use 
one of its derived classes (f stream, str stream, or stdiostream). 

class iostream inherits characteristics from both class istream 
and class ostream. See the descriptions of these parent classes for 
the details on functions and operators that are inherited. 

class iostream defines one constructor: 
iostream( streambuf *buf ) ; 

sets up buf as the associated streambuf. If buf is NULL, the effect 
is undefined. 

class ios, class fstream, class istream, 

class stdiostream, class strstream, class ostream 
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Synopsis #include <iostream.h> 

class istream : virtual public ios 

{ 

public: 

istream( streambuf *buf); 

virtual ~istream( ) ; 

int ipfx(int need = 0); 

istreamS operator >>(char *str); 
istreamS operator >>(unsigned char *str); 
istreamS operator >>( signed char *str); 

istreamS operator >>(charS c ) ; 
istreamS operator >>(unsigned charS c ) ; 
istreamS operator >>(signed chars c); 

istreamS operator >>(shortS sh); 
istreamS operator >>(unsigned shorts sh); 

istreamS operator >>(intS i); 
istreamS operator >>(unsigned intS i); 

istreamS operator >>( longs 1); 
istreamS operator >>(unsigned longs 1); 

istreamS operator >>(floatS f); 
istreamS operator >>(doubleS d); 
istreamS operator >>(long doubles Id); 

istreamS operator >>( streambuf *buf); 

istreamS operator >>( istreamS ( *f ) 

( istreamS ) ) ; 

istreamS operator >>( iosS ( *f )( iosS )) ; 

istreamS get(char *str, int len, char delim = ' \n ' ) ; 
istreamS get(unsigned char *str, int len, char delim = ' \n ' ) ; 
istreamS get(signed char *str, int len, char delim = '\n'); 
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istreamS getline(char *str, int len, char delim = ' \n ' ) ; 
istreamS getline(unsigned char *str, int len, char delim = ' \n ’ ) ; 

istreamS getline( signed char *str, int len, char delim = ' \n ' ) ; 

istreamS get( streambuf & sb, char delim = ' \n ' ) ; 

istreamS get(signed charS c); 
istreamS get(unsigned charS c); 
istreamS get(charS c ) ; 

int get( ) ; 

istreamS ignore(int n = 1, int delim = EOF); 

istreamS read(char *str, int n); 
istreamS read(unsigned char *str, int n); 
istreamS read(signed char *str, int n); 

int gcount( ) ; 
int peek( ) ; 

istreamS putback(char c); 
int sync( ) ; 

istreamS seekg( streampos pos); 

istreamS seekg( streamof f offset, seek_dir place); 

streampos tel lg ( ) ; 

); 


class istream is defined in the iostream.h header file and is the 
base class for those stream classes that support only input. It includes all 
the basic extraction functions (formatted input) on fundamental C+ + 
types, as well as a number of unformatted input functions and several 
functions that enable you to move the get pointer. It also includes one 
manipulator. These members are described in the following sections. 

You will not normally use class istream directly, but rather use 
one of its derived classes (if stream or istr stream). 
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Formatted Input 
Functions 


Provide for stream extraction 


class istream inherits characteristics from class ios. See the 
description of this parent class for the details on functions and operators 
that are inherited. 

class istream defines one constructor: 

istream: : istream( streambuf *buf ) ; 

initializes an istream and associates a streambuf with it. 

class istream has one destructor: 

virtual istream: :~istream( ) ; 
closes the istream. 

class istream defines an input prefix function that performs those 
operations that must be done before each formatting operation. This 
function is defined as follows: 

int istream: : ipfx( int need = 0); 

If any I/O state flags are set for the istream, this function returns 0 
immediately. If necessary, it flushes the ios (if any) tied to this 
istream. Flushing is necessary if need is 0 or if there are less than 
need characters available for input. 

If ios : : skipws is set and need is 0 then this function causes any 
leading white space in the input to be skipped. If an error occurs during 
this skipping, ipfx( ) returns 0. If no errors have occurred, this 
function returns 1. 

This function is called by all formatted extraction operations and 
should be called by user-defined extraction operators unless the first input 
operation used by the user-defined extraction operator is a formatted 
extraction. For user-defined operations, ipfx( ) should be called with 
the argument equal to 0. 

The functions named operator >> are called extraction operators. 

They are formatted input functions. They each call the input prefix 
function, ipf x ( 0 ) and do nothing else if it returns 0. If ipf x ( 0 ) does 
not return 0, the formatted input functions extract leading characters 
from the associated streambuf according to the type of their argument 
and the formatting flags in the ios. They all return the address of the 
istream. 
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Errors during extraction are indicated by setting the appropriate I/O 
state flags for the stream, as follows: 

ios: : f ailbit means that the actual input characters did not match 
the expected input format. 

ios: :badbit means that an error occurred during extraction of 
characters from the streambuf . 

The following list described each of the formatted input functions: 

istreamS istream: : operator >>(char *str); 
istreamS istream: : operator >>(unsigned char *str); 
istreamS istream: : operator >>(signed char *str); 
extract characters up to the next whitespace character. The 
terminating whitespace character is not extracted. If width ( ) is 
nonzero, these functions extract no more than width ( ) - 1 
characters and reset width ( ) to 0. These functions add a terminating 
null character, even if an error occurs during extraction. 
istreamS istream: : operator >>(charS c); 
istreamS istream: : operator >>(unsigned chars c); 
istreamS istream: : operator >>(signed charS c); 

extract a single character and store it in the argument. 
istreamS istream: : operator >>(shortS sh); 
istreamS istream: : operator >>(unsigned shorts sh) ; 
istreamS istream: : operator >>(intS i); 
istreamS istream: : operator >>(unsigned intS i); 
istreamS istream: : operator >>(long6 1); 
istreamS istream: : operator >>(unsigned longS 1); 

extract a number and store it in the argument. There may be a leading 
sign character (+ or -). If any of ios : : dec, ios : : oct, or 
ios :: hex is set in the formatting state, characters are extracted and 
converted according to the bit that is set. If none of these bits is set, 
then these functions expect any of the following formats: 

0 xhhh 
OXhhh 
0 ooo 
ddd 
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Extraction stops when it reaches an unacceptable character. The 
acceptable characters are 

0-7 

for octal conversion 
0-9 

for decimal conversion 
0-9, a-f, and A-F 

for hexadecimal conversion. 

ios : : f ailbit is set if no digits are found. 
istreamS istream: : operator >>(floatS f); 
istreamS istream: : operator >>(doubleS d) ; 
istreamS istream: : operator >>(long doubles Id); 
extract a floating-point number and store it in the argument. The 
expected input format is an optional sign, followed by a decimal 
mantissa (optionally including a decimal point), followed by an 
optional floating-point exponent. The exponent may contain either an 
uppercase or a lowercase E, and may have a + or a - following the E. 
Extraction stops when EOF is encountered, or when a character is 
read which cannot continue the previous input in a valid manner, 
ios : : f ailbit is set if there are no digits to extract, or if the 
format is not correct. 

istreamS i stream :: operator >>(streambuf *buf ) ; 

extracts all characters from the istream and inserts them into the 
streambuf . Extraction stops when no more characters can be 
obtained from the istream. 

istreamS istream: : operator >>( istreamS ( *f ) 

( istreamS ) ) ; 

istreamS istream: : operator >> ( iosS ( *f ) ( iosS ) ) ; 
are for support of simple manipulators. Although these operators 
resemble an extraction in appearance, they are used to manipulate the 
stream rather than to extract characters from it. The argument to 
either of these operators is a manipulator function that modifies its 
ios or istream argument in some manner. 
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Unformatted Input The following functions are the unformatted input functions. They each 
Functions call ipf x ( 1 ) first and do nothing else if 0 is returned. 

istreamS istream: : get ( char *str, int len, char delim 
= ' \n' ) ; 

istreamS istream: : get ( unsigned char *str, int len, 
char del im = ' \n ' ) ; 

istreamS istream: : get ( signed char *str, int len, 
char delim = '\n'); 

extract up to len - 1 characters. Extraction stops when a delim 
character is extracted, no more characters are available, or when len 
- 1 characters have been found. These functions store a terminating 
null character in the array, ios: :failbit is set only if no 
characters at all were extracted. 

istreamS istream: :getline( char *str, int len, char 
delim = ' \n ' ) ; 

istreamS istream: : getline ( unsigned char *str, int 
len, char delim = '\n'); 

istreamS istream: :getline ( signed char *str, int len, 
char delim = '\n'); 

behave like the get ( ) functions, except that the terminating delim 
character (if found) is extracted. A terminating null character is 
always stored in the array. 

istreamS istream: : get ( streambuf S sb, char delim = 

' \n' ) ; 

extracts characters up to the next delim character or EOF and 
inserts them into sb. The delim character is not extracted or 
inserted, ios : : f ailbit is set if an error occurs while inserting into 
sb. 

istreamS istream: : get ( signed charS c); 
istreamS istream: : get ( uns igned charS c); 
istreamS istream: : get ( char S c); 

extract a single character, ios : : f ailbit is set if no characters can 
be extracted. 

int istream: : get () ; 

extracts a single character and returns it. EOF is returned if no 
characters can be extracted, ios: :failbit is never set. 
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istreamS istream: : ignore ( int n = 1, int delim = 

EOF) ; 

extracts up to the next n characters, or up to the next delim 
character, ios: :failbit is never set. 
istreamS istream: : read( char *str, int n) ; 
istreamS istream: : read ( uns igned char *str, int n) ; 
istreamS istream: : read( signed char *str, int n) ; 

extract the next n characters and store them into the array pointed to 
by str. If fewer than n characters can be extracted, ios: :failbit 
is set. 

class istream includes several other functions, as described in the 
following list. 

int istream: : gcount () ; 

returns the number of characters extracted by the last unformatted 
extraction function. Formatted extraction functions may change the 
value of this function in unexpected ways, 
int istream: :peek( ) ; 

returns EOF if ipf x ( 1 ) returns 0 or if no characters remain to be 
extracted. Otherwise it returns the next character in the stream 
without extracting it. 

istreamS istream: : putback ( char c); 

does nothing if any bits are set in the stream’s I/O state. If no bits are 
set in the stream’s I/O state, this function pushes back the character c 
so it will be the next character extracted, c must be the same as the 
last character extracted from the istream. ios::badbitissetif 
the streambuf cannot push c back, 
int istream: : sync () ; 

calls sync( ) on the associated streambuf. This function returns 
whatever the streambuf : : sync( ) call returned. 
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class istream 

(continued) 


See Also 


Provide for stream extraction 


istreamS istream: : seekg ( streampos pos); 

istreamS istream: : seekg ( streamof f offset, seek_dir 

place ) ; 

move the get pointer of the associated streambuf . pos is a value 
returned by a previous call to tellg( ). offset and place are 
explained in the streambuf : : seekof f ( ) description, 
streampos istream: : tellg( ) ; 

returns the current streampos of the get pointer of the associated 
streambuf. 

class ifstream, class ios, class iostream, class 
istrstream, class ostream 
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class istrstream 

Synopsis 


Description 
Parent Class 
Constructors 


Destructors 


Provide formatted string input 

jfinclude <strstream.h> 

class istrstream : public strstreambuf , 
public istream 


public: 

istrstream(char *str); 
istrstream(char *str, int size); 
~istrstream( ) ; 
strstreambuf* rdbuf(); 

} ; 


class istrstream implements an input only stream whose source is 
an area of memory. This class supports string (array) input by 
customizing the input operations defined in class istream. The 
streambuf associated with class istrstream is a strstreambuf. 

class istrstream inherits characteristics from class istre am, 
which inherits characteristics from class ios. See the descriptions of 
these parent classes for the details on functions and operators that are 
inherited. 

class istrstream has two constructors: 

istrstream: : istrstream( char *str) ; 

creates a static mode istrstream such that extraction operations on 
the stream will fetch the characters of str, up to the terminating \0. 
str must be null-terminated. The \0 character is not fetched. Seeks 
are allowed within the array. 

istrstream: : istrstream( char *str, int size); 

creates a static mode istrstream such that extraction operations on 
the stream will fetch characters from the array starting at str and 
extending for size bytes. Seeks are allowed within the array. 

For a discussion of dynamic mode and static mode streams, see the 
description of class strstreambuf, later in this chapter. 

class istrstream has one destructor: 

istrstream: :~istrstream( ) ; 

closes the stream. For dynamic stream objects, closing means delete 
the array, unless it has been frozen. For static stream objects, closing 
is meaningless. 
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(continued) 

Member Functions The following function is a member of class istrstream: 
strstreambuf * istrstream: :rdbuf ( ) ; 

returns a pointer to the strstreambuf associated with the stream. 

Example ((include <strstream.h> 

// Example using an istrstream (Input-only String-based stream) 
int main(void) 

{ 

// Declare an istrstream object called "mystream" and initialize 
// it to read bytes from the string "123 456". 
istrstream mystream( " 123 456"); 

// Declare a pointer to an istrstream object 
istrstream *stream_p; 

int i, j; 
double d; 
char c; 

// Read two integers from the string attached to "mystream" 
mystream >> i >> j; 

// Print the integers to the program's standard output 
cout << "The integers are " << i << " and " << j << endl; 

// Allocate a new static-mode istrstream using "new" 
stream_p = new istrstream( "3 . 765 x"); 

*stream_p >> d >> c; 

cout << "The number is " << d << " and the letter is " « c << endl 

// Free the object just allocated. This will call the destructor 
// for the stream and therefore close the file, 
delete stream_p; 

// Destructors for the other streams will automatically be called, 
return 0; 
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See Also class strstream, class str streambuf , class ostrstream 
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class ofstream 

Synopsis 


Description 
Parent Class 

Constructors 


Provide formatted file I/O 

((include <fstream.h> 

class ofstream : public ostream 

( 

public : 

of stream( ) ; 

ofstream(const char *name, int mode = ios::out); 
virtual ~ofstream(); 

void open( const char *name, int mode = ios::out); 
void close( ) ; 

void setbuf(char *p, size_t len); 
f ilebuf * rdbuf ( ) ; 


class ofstream implements an output only stream whose destination 
is a file. The streambuf associated with the I/O operations is a 
f ilebuf (instead of a str streambuf or stdiobuf). 

class ofstream inherits characteristics from class ostre am, 
which inherits characteristics from class ios. See the descriptions of 
these parent classes for the details on functions and operators that are 
inherited. 

There are two sets of constructors for class ofstream, as follows: 

ofstream: :ofstream( ) ; 

creates an unopened stream of the appropriate type, 
of stream: : of stream( const char *name, int mode = 
ios : : out ) ; 

creates a stream of the appropriate type, named name, using the 
specified mode. The ofstream constructor behaves as if ios : : out 
was set in the mode argument, whether or not it was set by the caller. 

See the description of enum open__mode, later in this chapter, for 
information on the available modes. If the open fails, the stream’s 
status is reflected in its I/O state flags. See the description of 
enum io_state, later in this chapter, for information on the I/O 
state flags. 
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class ofstream 

( continued ) 
Destructors 

Member Functions 


Example 


Provide formatted file I/O 


class ofstream has one destructor: 

virtual ofstream: :~ofstream( ) ; 
closes the stream, if opened. 

The following descriptions give the purpose and return type of the 
member functions, as well as any other appropriate information. 

void of stream: : open( const char *name, int mode = 
ios : : out ) ; 

opens the named file using the specified mode, ofstream: :open( ) 
behaves as if ios : : out was set in the mode argument, whether or 
not it was set by the caller. See the description of enum open_mode, 
later in this chapter, for information on the available open modes. 

This function does not have a return value. If an error occurs 
during the open, the ios : : f ailbit bit is set in the stream’s I/O 
state. For example, the call to rdbuf ( )->open( ) may fail, 
void of stream: : close () ; 

closes the connection between the appropriate object and its associated 
file. Unless an error occurs, then all bits in the object’s I/O state are 
set to zero. The close could fail if the call to rdbuf ( ) - >close ( ) 
fails. These functions have no return value, 
void of stream: : setbuf ( char *p, size_t len); 

calls f ilebuf : : setbuf (p, len). This function has no return 
value. 

filebuf* of stream: : rdbuf () ; 

returns a pointer to the filebuf associated with the stream. 

((include <fstream.h> 

// Example using an ofstream (Output-only File-based stream) 
int main(void) 

{ 

// Declare an ofstream object called "mystream" and initialize 
// it to write bytes to the file "myofile.dat" 
ofstream mystream( "myofile.dat" ) ; 

// Declare an unopened ofstream object called "mystream2" 
ofstream mystream2; 

// Declare a pointer to an ofstream object 
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(continued) 

ofstream *stream_p; 

if ( Imystream) 

{ 

cout << "Error opening file V'myof ile.datX" ! " << endl; 
return 20; 


// Write an integer to the file attached to "mystream" 
cout << "writing \"123\" to file V'myof ile.datX"" << endl; 
mystream << 123; 

// Initialize the unopened "mystream2" stream to write to 
// the file "myofile2.dat" 
mystream2 . open ( "myof ile2 . dat" ) ; 

if ( !mystream2 ) 

( 

cout << "Error opening file V'myof ile2 .dat\" ! " << endl; 
return 20; 

} 

// Write an integer to "myofile2.dat" 

cout << "writing \"456\" to file V'myof ile2.dat\"" << endl; 
mystream2 << 456; 

// Allocate a new ofstream using "new" and use it to write to 

// the file "myofile3.dat" 

stream_p = new ofstream("myofile3.dat"); 

if(!stream_p II !*stream_p) 

{ 

cout << "Error opening file V'myof ile3 .dat\" ! " << endl; 
return 20; 

) 

cout << "Writing \"789\" to file V'myof ile3.dat\"" << endl; 
*stream_p << 789; 

// Free the object just allocated. This will call the destructor 
// for the stream and therefore close the file, 
delete stream_p; 
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class ofstream 

(continued) 


Provide formatted file I/O 


// Destructors for the other streams will automatically be called, 
return 0; 

) 


See Also class filebuf, class fstream, class ifstream, class ios, 
class ostream 
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Class OStream Provide for stream insertion 

Synopsis ((include <iostream.h> 

class ostream : virtual public ios 

{ 

public: 


ostream( streambuf 

*buf ) ; 

virtual ~ostream( ) ; 
int opfx( ) ; 
void osf x( ) ; 

ostreamS 

operator 

«(char c); 

ostreamS 

operator 

<<(signed char c) ; 

ostreamS 

operator 

<<(unsigned char c) ; 

ostreamS 

operator 

<<(const char *str ) ; 

ostreamS 

operator 

<<(const unsigned char *str); 

ostreamS 

operator 

<<(const signed char *str); 

ostreamS 

operator 

<<(short sh) ; 

ostreamS 

operator 

<<(unsigned short sh); 

ostreamS 

operator 

<<(int i) ; 

ostreamS 

operator 

<<(unsigned int i); 

ostreamS 

operator 

<<(long 1) ; 

ostreamS 

operator 

<<(unsigned long 1) ; 

ostreamS 

operator 

<<(float f); 

ostreamS 

operator 

<<(double d) ; 

ostreamS 

operator 

<<(void *vp) ; 

ostreamS 

operator 

<<(streambuf *buf); 

ostreamS 

operator 

<<(ostreamS(*f ) 
(ostreamS ) ) ; 

ostreamS 

operator 

<<(iosS(*f ) (iosS) ) ; 


ostreamS put (char c); 
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class ostream 

( continued ) 


Description 


Parent Class 


Constructors 


Destructors 


Prefix and Suffix 
Output Functions 


Provide for stream insertion 


ostreamS write(const char *str, int n); 
ostreamS write(const signed char *str, int n); 
ostreamS write(const unsigned char *str, int n); 

ostreamS flush(); 

streampos tel lp ( ) ; 

ostreamS seekp( streampos pos ) ; 

ostreamS seekp(streamof f offset, seek_dir place); 


ostreamS endl ( ostreamS ) ; 
ostreamS ends ( ostreamS ) ; 
ostreamS flush( ostreamS ) ; 

class ostream is declared in the iostream.h header file and is the 
base class for those classes that support only output. It includes all the 
basic insertion operators (formatted output) on fundamental C+ + types, 
as well as a number of unformatted output functions and functions 
designed to change the stream position. In addition, some output 
manipulators are defined for use with this class. 

You will not normally use class ostream directly, but rather one of 
its derived classes, of stream or ostr stream. 

class ostream inherits characteristics from class ios. See the 
description of this parent class for the details on functions and operators 
that are inherited. 

class ostream defines one constructor: 

ostream: :ostream( streambuf *buf ) ; 

initializes an ostream and associates a streambuf with it. 

class ostream defines one destructor: 

virtual ostream: :~ostream( ) ; 
closes the ostream. 

Certain operations are defined to happen either before or after formatted 
output through an ostream. The prefix operations are done by 
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class ostream 

(continued) 


Formatted Output 
Functions 


Provide for stream insertion 


ostream: : opfx( ) and the suffix operations are done by 
ostream: : osf x ( ) . 

int ostream: :opfx( ) ; 

performs prefix operations for an ostream. This function returns 0 
and does nothing else if any bits in the stream’s I/O state are set; it 
returns 1 otherwise. If the ostream is tied to another stream, the 
other stream is flushed. For more information on the tie ( ) and 
f lush( ) functions, see “Frequently Used Stream Class Member 
Functions,” earlier in this chapter. 

By convention, opfx( ) is called before any formatted output 
operation on a stream. If it returns 0 (meaning one or more bits are 
set in the stream’s I/O state) the output operation is not performed. 
Each of the built-in inserters follows this convention. User-defined 
formatted output functions should also follow this convention by 
calling this function and checking the return code before doing any 
output. 

void ostream: : osf x () ; 

performs suffix operations on the stream. If ios : :unitbuf is set, 
this ostream is flushed. If ios : : stdio is set, cout and cerr are 
flushed. This function should be called at the end of any formatted 
output function that does unformatted output on the ostream. It 
need not be called if the last output operation on the ostream was 
formatted. 

The functions named operator << are called inserters (because they 
insert values into the output stream). All inserters are formatted output 
operations and as such follow the formatted output conventions 
mentioned previously. 

All of the inserters do the following: First, they call opfx( ) and if it 
returns 0, they do nothing else. If there is no error, they then convert 
the input argument to a converted value (a sequence of characters), based 
on the argument’s type and value and on the formatting flags set for the 
stream. The rules for construction of the converted value are given here 
for each inserter. 

Once a converted value has been determined, it is copied, possibly with 
the addition of fill characters, to an output field. The characters of the 
output field are then inserted into the stream’s buffer. The 
ios: : width ( ) function for the stream determines the minimum 
number of characters in the output field. If the converted value had fewer 
characters, fill characters (defined by the value of ios :: fill ( ) for the 
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(continued) 


stream) are added to pad out the field. The placement of fill characters is 
as follows: 

ios: : right places the converted value in the rightmost portion of 
the field (leading padding). 

ios : : lef t places the converted value in the leftmost portion of 
the field (trailing padding). 

ios: :internal places the sign and base indicators of the converted 
value in the leftmost portion of the field and the 
remainder in the rightmost portion (internal padding). 

Truncation cannot occur when copying the converted value to an output 
field, regardless of the value of width ( ). 

Once the converted value is constructed and the field padded to be at 
least ios : : width ( ) characters wide, ios : : width ( ) is reset to 0 and 
o s f x ( ) is called. All inserters indicate errors by setting I/O state flags 
in the ostream, as necessary. Inserters always return a reference to 
their ostream argument. 

The following list describes the formatted output functions. 

ostreamS ostream: : operator <<(char c); 
ostreamS ostream: : operator <<(signed char c); 
ostreamS ostream: : operator <<(unsigned char c ) ; 

convert the argument to the char c. 
ostreamS ostream: : operator <<(const char *str); 
ostreamS ostream: : operator <<(const unsigned char 
*str ) 

ostreamS ostream: : operator «(const signed char 
*str ) ; 

convert the argument to a sequence of chars, up to but not including 
a \0 character, pointed to by const char* str. 
ostreamS ostream: : operator <<(short sh); 
ostreamS ostream: : operator <<(unsigned short sh) ; 
ostreamS ostream: : operator <<(int i); 
ostreamS ostream: : operator <<(unsigned int i); 
ostreamS ostream :: operator <<(long 1); 
ostreamS ostream: : operator <<(unsigned long 1); 

convert the value of the argument to a sequence of digits, preceded by 
a leading minus sign (-) if the argument is negative. 
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(continued) 


Provide for stream insertion 


If the following format flags within the ostream are set, they affect 
the converted value as follows: 

ios : : showpos 

causes a leading plus sign (+) to be included in the converted 
value if the value is positive, 
ios:: dec, ios::oct, and ios : : hex 

determine the base used for the converted value, 
ios : : showbase 

causes the converted value to indicate the appropriate base as 
follows: 

decimal makes no change to the converted value. 

octal prefixes the converted value with a single 0 digit. If 
the value is 0 there is only one zero digit. 

hexadecimal prefixes the converted value with Ox. If 

ios : : uppercase is set, a leading OX is used 
instead. 

If both a sign representation ( + or -) and a base representation 
appear in the converted value, the sign appears first, 
ostreamfi ostream: : operator <<(float f); 
ostreamS ostream: : operator <<(double d) ; 

converts the argument to a character representation of its value in 
one of two formats: 

D fixed notation (“±ddd. ddd“) 

□ scientific notation (“ ± d. ddde±dd“). 

These formats are described in detail in the enum 
format-state description earlier in this chapter. The format of 
the converted value is affected by the settings of the following 
format flags: 

ios: :fixed or ios: scientific 

determines the overall representation format. If neither is set 
then the overall format is scientific if the exponent is less than 
- 4 or greater than the precision. Fixed notation is chosen 
otherwise. 
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(continued) 

ios : : showpoint 

causes the decimal point to be shown, followed by at least one 
digit. If showpoint is not set and all digits after the decimal 
point are zero, these digits and the decimal point are dropped, 
ios : : uppercase 

causes the e in scientific notation to be E and the x in 
hexadecimal notation to be X. 
ios : : showpos 

causes a leading plus sign (+) to be output for positive values. 

ostreamt ostream: : operator <<(void *vp); 

converts the value of the pointer vp to an unsigned long and 
represents it as if ios : :hex and ios : : showbase were set. 
ostreamS ostream: : operator <<(streambuf *buf ) ; 
fetches all the characters in buf and inserts them into the output 
stream, provided no bits are set in buf ‘s I/O state. No padding is 
done. If any bits are set in buf ‘s I/O state, this function returns 
immediately. 

ostreamt ostream :: operator <<( ostreamS ( *f ) 

( ostreamS ) ) ; 

ostreamS ostream: : operator << ( ios 6 ( *f ) ( ios S ) ) ; 
are for support of simple manipulators. Although these operators 
resemble an insertion in appearance, they are used to manipulate 
the stream rather than to insert characters into it. The argument to 
either of these operators is a manipulator function that modifies its 
ios or ostream argument in some manner. 

Unformatted Output The following functions are for support of unformatted output to a 
Functions stream. Because they are unformatted operations they do not call 

opfx( ) and osfx( ). However, these functions check whether any I/O 
state flags are set for the ostream and if so, take no additional action. 
All inserters indicate errors by setting I/O state flags in the ostream. 
Each of these functions returns a reference to its argument ostream. 
ostreamS ostream :: put ( char c); 
inserts its argument into the stream. 
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(continued) 


Other Member 
Functions 


Manipulators 


Provide for stream insertion 


ostreamS ostream: : write ( const char *str, int n); 
ostreamg ostream: :write( const signed char *str, int 
n ) ; 

ostreamS ostream: : write ( const unsigned char *str, 
int n) ; 

insert n characters starting at str into the stream. The characters are 
treated as plain chars independent of their actual type. The null 
character is treated the same as any other character. 

The following functions are also members of class ostream. 

ostreamS ostream :: f lush () ; 

calls rdbuf( )->sync( ). For more information, see the description 
of streambuf : : sync ( ) . 
streampos ostream: : tellp( ) ; 

returns the stream’s current put pointer position. For more 
information, see the descriptions of streambuf : : seekof f ( ) and 
streambuf: :seekpos( ). 
ostreamS ostream :: seekp ( streampos pos); 
ostreamS ostream: : seekp ( streamof f offset, seek_dir 
place ) ; 

reposition the stream’s put pointer. For more information, see the 
descriptions of streambuf : : seekof f ( ) and 
streambuf: :seekpos( ). 

The following functions are called manipulators. They are intended to be 
used with the inserters to manipulate the stream in specified ways. These 
manipulators do nothing if any of the stream’s I/O state flags are set. 
They signal errors by setting flags in the stream’s I/O state. They each 
return their argument. 

ostreamS endl ( ostreamS ) 

inserts a \n character into the stream. For example: 

ifinclude <iostreara. h> 

float mynum=3.2; 

// Writes "mynum is:" and the value 
of mynum on one line, 
cout << "mynum is: " << mynum << endl; 
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(continued) 


Provide for stream insertion 


ostreamS ends ( ostreamS ) 

inserts a \0 character into the stream. The following example uses a 
strstream: 

Uinclude <iostream.h> 
strstream mystream; 
float mynum=3.2; 

// Writes mynum to mystream. 
mystream << "mynum is: " << mynum << 
ends ; 

ostreamS f lush ( ostreamS ) 
calls ostream. f lush( ) . 


See Also class ios, class iostream, class istream 
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class ostrstream 

Synopsis 


Description 

Parent Class 
Constructors 


Provide formatted string I/O 

((include <strstream.h> 

class ostrstream : public strstreambuf , 
public ostream 


public: 

ostrstream(char *str, int size, int mode = ios::out); 
ostrstream( ) ; 

~-ostrstream( ) ; 

char* str ( ) ; 
int pcount(); 
strstreambuf* rdbuf(); 


class ostrstream implements an output only stream whose 
destination is an area of memory. This class supports string (array) 
output by customizing the output operations defined in class 
ostream. The streambuf associated with class ostrstream is a 
strstreambuf. 

class ostrstream inherits characteristics from class ostream 
and class ios. See the descriptions of these parent classes for the 
details on functions and operators that are inherited. 

class ostrstream has two constructors: 

ostrstream: : ostrstream( char *str, int size, int mode 
= ios : : out ) ; 

creates a static mode ostrstream referencing an area of size bytes 
starting at the character pointed to by str. The get pointer is 
positioned at the beginning of the array. The put pointer is also 
positioned at the beginning of the array unless either the ios : rate 
or ios : : app bit is set in mode; if either of these bits is set, the 
put pointer is positioned at the space that contains the first null 
character. Seeks are allowed anywhere within the array. 

ostrstream: :ostrstream( ) ; 

creates a dynamic mode ostrstream. This involves dynamically 
allocating space to hold stored characters. Seeks are not allowed. 

For a discussion of dynamic mode and static mode streams, see the 
description of class strstreambuf, later in this chapter. 
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( continued ) 

Destructors class ostrstream has one destructor: 

ostrstream: :~ostr s tr eam( ) ; 

closes the stream. For dynamic stream objects, closing means delete 
the array, unless it has been frozen. For static stream objects, closing 
is meaningless. 

Member Functions The following functions are members of class ostrstream. 
char* ostrstream: : str () ; 

calls str ( ) on the associated streambuf. This function returns 
whatever the streambuf : : str ( ) call returned, 
int ostrstream: : pcount () ; 

returns the number of stored bytes, 
strstreambuf * ostrstream: : rdbuf ( ) ; 

returns a pointer to the strstreambuf associated with the stream. 

Example ((include <strstream.h> 

// Example using an ostrstream (Output-only String-based stream) 
int main(void) 

{ 

// Declare an ostrstream object called "mystream" 
ostrstream mystream; 

// Write two integers to the string attached to "mystream" 
mystream << 123 << 456; 

// Obtain the contents of mystream and send them to stdout 
cout << "mystream contains: " << mystream. str () ; 

// The destructor for the stream will automatically be called, 
return 0; 


See Also class istrstream, class strstream, class strstreambuf 
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class 

stdiostream 

Synopsis 


Description 


Parent Class 
Constructors 
Member Functions 


Provide formatted I/O in programs using C and C+ + 


((include <stdiostream. h> 

class stdiostream : public iostream 

I 

public: 

stdiostream(FILE ♦file) ; 

FILE* stdiof ile( ) ; 
stdiobuf * rdbuf ( ) ; 

); 


class stdiostream is declared in the stdiostream. h header file. 
It provides iostream access to an external file accessed by C functions 
using the ANSI standard I/O interfaces declared in stdio .h. Use of 
class stdiostream enables a program to use stdio output and 
C++ iostream output in the same output file. Similarly, 
class stdiostream enables your program to use stdio input and 
C++ iostream input to process the same input file. 

class stdiostream inherits characteristics from class iostream, 
which in turn inherits characteristics from class i stream, class 
os tr earn, and class ios. See the descriptions of these parent classes 
for the details on functions and operators that are inherited. 

class stdiostream has one constructor: 

stdiostream: : stdiostream( FILE *file) ; 

creates a stream from the open FILE* file. The constructor 
assumes that the file is open. 

The following descriptions give the purpose and return type of the 
member functions, as well as any other appropriate information, 
stdiostream: : FILE* stdiofilef); 

returns the FILE* associated with this stream, 
stdiobuf* stdiostream: : rdbuf () ; 

returns a pointer to the stdiobuf associated with the stream. 


See Also 


class stdiobuf 
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class streampos 

Synopsis 


Description 


Constructors 


Mark a stream location 

((include <iostream.h> 

class streampos 

( 

public: 

streampos ( ) ; 
streampos (long n ) ; 
operator long(); 
fpos_t* fpos(); 


class streampos is declared in the iostream.h header file and is 
used to record or specify a position in a stream. This class is for use only 
with streams that support seeking, class streampos is used as a 
return value for the various stream positioning functions defined in the 
different buffering classes. 

Most streampos values are similar to C f pos_t values; that is, they 
record file position values in a way private to the implementation. 

Because these values are probably not useful for user-defined stream 
classes, it is also possible to create streampos objects with integral 
values, streampos objects with integral values are probably not useful 
for positioning fstreamor stdiostream objects. 

This class defines two constructors: 

streampos : : streampos ( ) ; 

creates a streampos object with an unknown value, 
streampos :: streampos ( long n) ; 

creates a streampos object from the value n. All kinds of stream 
buffers support the following values of n: 

streampos ( 0 ) 

indicates the beginning of the stream, 
streampos ( EOF ) 

indicates the end of the stream. 


strstream objects created from other values of n are not useful for 
positioning fstreamor stdiostream objects. 
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(continued) 

Member Functions This class defines two member functions: 

streampos :: operator long(); 

reduces the value of the streampos to a long integer. The value of 
( long) ( streampos ( long_val ) ) is defined to be equal to 
long_val. The result of converting a streampos not constructed 
from a long is undefined. 
fpos_t* streampos :: fpos () ; 

returns a pointer to an f pos_t contained in the streampos. This 
f pos_t contains a valid value only if this streampos was returned 
from a call to seekof f ( ) or seekpos ( ) on a f ilebuf or 
stdiobuf object. 
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class strstream 

Synopsis 


Description 

Parent Class 
Constructors 


Provide formatted string I/O 

Sinclude <strstream.h> 

class strstream : public strstreambuf , 
public iostream 

( 

public: 

strstream( char *str, int size, int mode = ios::out); 
strstream( ) ; 

~strstream( ) ; 

char* str ( ) ; 
int pcount( ) ; 
strstreambuf* rdbuf ( ) ; 

); 


class strstream and its associated classes class istrstream 
and class ostrstream are declared in the strstream. h header 
file. These classes support string (array) I/O by customizing the I/O 
operations defined in the base classes i stream, os tr earn, and 
iostream. 

class strstream inherits characteristics from class iostream, 
which inherits characteristics from class ios. See the descriptions of 
these parent classes for the details on functions and operators that are 
inherited. 

class strstream has two constructors. 

strstream: : strstream! char *str, int size, int mode = 
ios : : out ) ; 

creates a static mode strstream referencing an area of size bytes 
starting at the character pointed to by str. The get pointer is 
positioned at the beginning of the array. The put pointer is also 
positioned at the beginning of the array unless either the ios : : ate 
or ios : : app bit is set in mode; if either of these bits is set, the 
put pointer is positioned at the space that contains the first null 
character. 

strstream: :strstream( ) ; 

creates a dynamic mode strstream. This involves allocating space to 
hold stored characters. Seeks are not allowed. The get pointer is 
positioned at the beginning of the array. 



C+ + Library Reference 685 


class strstream 

(continued) 


Destructors 


Member Functions 


Example 


Provide formatted string I/O 


For a discussion of dynamic mode and static mode streams, see the 
description of class str streambuf , later in this chapter. 

class strstream has one destructor: 
strstream: :~strstream( ) ; 

closes the stream. For dynamic stream objects, closing means delete 
the array, unless it has been frozen. For static stream objects, closing 
is meaningless. 

The following functions are members of class strstream: 
char* strstream: : str () ; 

calls str ( ) on the associated streambuf. This function returns 
whatever the streambuf : : str ( ) call returned, 
int strstream: : pcount () ; 

returns the number of stored bytes, 
strstreambuf * strstream: : rdbuf ( ) ; 

returns a pointer to the strstreambuf associated with the stream. 

This example creates a strstream, inserts a string and a number, then 
extracts them again, writing the contents of mystream to cout. 

strstream mystream; // dynamic mode strstream 
float mynum=3.2; 
float num2; 

// Write mynum to mystream. 
mystream << mynum << ends; 

// Extract the contents of mystream and 
store them in num2. 
mystream >> num2; 

// Get the string from mystream and write 
it to cout. 

cout << mystream. str( ) ; 


See Also class istrstream, class ostrstream, class strstreambuf 
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Buffer Class 
Descriptions 


This section provides the descriptions of the buffer classes, such as 
filebuf and strstreambuf . 

Using these classes is an advanced programming technique and is not 
required for simple C+ + programs that use I/O. As with the stream 
class descriptions, the protected interface to the buffer classes is not 
included in t class descriptions that follow, although it is implemented. 
The following classes are described in this section: 

filebuf 

stdiobuf 

streambuf 

strstreambuf 

Note: The term character in the following class and function 
descriptions refers to either a char, a signed char, or an 
unsigned char. 
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class filebuf 

Synopsis 


Description 


Parent Class 


Provide file I/O 

jfinclude <fstream.h> 

class filebuf : public strearabuf 

{ 

public: 

filebuf ( ) ; 

virtual ~f ilebuf ( ) ; 

int is_open(); 

filebuf* open(const char *name, int mode); 
filebuf* close( ) ; 

virtual streampos seekoff (streamoff offset, seek_dir place, 
int mode = ios : : in I ios : :out) ; 
virtual streampos seekpos( streampos pos, 
int mode = ios: : in I ios: :out) ; 
virtual streambuf* setbuf(char *p, size_t len); 
virtual int sync(); 


The fstream.h header file defines class filebuf. filebuf objects 
represent the lowest level of file I/O that is standard C++. They provide 
a specialized form of streambuf that uses a file as the source or 
destination for characters. Input corresponds to file reads and output 
corresponds to file writes. For filebuf objects, the get and put pointers 
are tied together. That is, if you move one, you move the other. If the file 
has a format that allows seeks, a filebuf allows seeks, filebuf I/O 
guarantees at least four characters of putback. You do not need to 
perform any special action between reads and writes (in contrast to 
standard C I/O, where such seeks are required). 

When a filebuf is connected to a file, the filebuf is said to be 
open. There is no default open mode, so you must always specify the 
open mode when you create a filebuf. 

filebuf objects may directly access the native I/O facilities of the 
system on which they are implemented. For Version 6.50 of the SAS/C 
Development System, filebuf objects are implemented in terms of C 
file*s. This may be changed in later versions of this library and no 
assumptions should be made of this particular implementation. 

class filebuf inherits characteristics from class streambuf. See 
the description of this parent class for the details on functions and 
operators that are inherited. 
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class filebuf 

(continued) 

Constructors 


Destructors 


Non-Virtual Member 
Functions 


Virtual Member 
Functions 


Provide file I/O 


class filebuf defines one constructor: 

filebuf : : filebuf ( ) ; 
creates an unopened file. 

class f ilebuf has one destructor: 

virtual f ilebuf : :~f ilebuf () ; 
closes the file, if opened. 

The following non-virtual functions are defined in class filebuf. The 
virtual functions are described later in this section. 

int f ilebuf :: is_open( ) ; 

returns a nonzero value if the filebuf is connected to an open file; 
returns 0 otherwise. 

filebuf* f ilebuf :: open( const char *name , int mode); 
opens a file named name and connects the filebuf to it. If the open 
is successful, open( ) returns a pointer to the filebuf. If an error 
occurs during the open (for example, if the file is already open), 
open( ) returns 0. See the description of enum open_mode, earlier 
in this chapter, for information about the mode argument, 
filebuf* f ilebuf :: close () ; 

causes any outstanding output to be flushed, then closes the file and 
disconnects the filebuf from it (even if errors occur). Also, the 
f ilebuf ‘s I/O state is cleared. If the close is successful, close ( ) 
returns a pointer to the filebuf. If an error occurs during the close, 
close ( ) returns 0. 

The following functions override their base class definitions (in class 
streambuf ) . 

virtual streampos f i lebuf : : seekof f ( streamof f offset, 
seek_dir place, int mode = ios : : in I ios : : out ) ; 

sets the get and put pointers to a new position, as indicated by place 
and offset. (Descriptions of offset and place are contained in 
the streambuf : : seekof f ( ) description.) 

This function returns the new position, or streampos ( EOF ) if an 
error occurs (for example, the file may not support seeking, or you 
may have requested a seek to a position preceding the beginning of the 
file). The position of the file after an error is undefined. Some files 
support seeking in full and some impose lesser or greater restrictions 
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class filebuf Provide file I/O 
(continued) 


on seeking, seekof f ( ) corresponds to the C f seek function and 
seekpos ( ) corresponds to the C fsetpos function. Rules for these 
similar C functions are in Chapter 7. 

For filebuf objects, the get and put pointers are the same 
(moving either one moves the other). Therefore, you do not have to 
use the last argument, mode. 

virtual streampos filebuf :: seekpos ( streampos pos, 
int mode = ios : : in I ios : : out ) ; 

sets the get and/or put pointers to a new position, as indicated by 
streampos. This function returns the new position, or 
seekpos (EOF) if an error occurs. For filebuf objects, the get and 
put pointers are the same (moving either one moves the other). 

Because of this, you do not have to use the last argument, mode, 
virtual streambuf* f i lebuf : : setbuf ( char *p f size_t 
len) ; 

offers the character array starting at p and containing len bytes as a 
buffer for use by the filebuf. If p is null or len is less than or 
equal to 0, the filebuf is unbuffered. (However, buffering by the 
SAS/C Library and the operating system may still take place.) This 
function must be called before any I/O is requested for this filebuf 
and can be called only once for the filebuf. Under normal 
conditions, setbuf ( ) returns a pointer to the filebuf. 

If this function is called after I/O has been requested for the 
filebuf, this function does nothing and returns NULL. If this 
function is called more than once, subsequent calls for the filebuf 
do nothing except return NULL. This function does not affect the I/O 
state of the filebuf. 
virtual int f ilebuf : : sync ( ) ; 

tries to force the state of the get or put pointer of the filebuf to be 
synchronized with the state of the file it is associated with. This 
attempt at synchronization may result in the following: 

□ characters being written to the file, if some have been buffered for 
output. All characters may not be written immediately due to 
additional buffering performed by the operating system. 

□ an attempt to seek the file, if characters have been read and 
buffered for input. 

This function usually returns 0; if synchronization is not possible it 
returns EOF. 
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class filebuf Provide file I/O 
(continued) 


See Also class f stream, class if stream, class of stream 
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Class Stdiobuf Provide I/O in a program using C and C+ + 


Synopsis ((include <stdiostream.h> 

class stdiobuf : public streambuf 

{ 

public: 

stdiobuf (FILE *file); 
virtual ~stdiobuf ( ) ; 
int is_open(); 

FILE* stdiof ile( ) ; 

streampos seekof f ( streamof f offset, seek_dir place, 
int mode = ios: : in I ios: :out) ; 

streampos seekpos( streampos pos, int mode = ios: : in I ios: : out) ; 
virtual int sync(); 

}; 

Description The stdiostream.h header file declares class stdiobuf. 

stdiobufs are intended to be an interface to ANSI C style FILE*s on 
those systems that provide FlLE*s. Calls to stdiobuf member 
functions are mapped directly to calls to ANSI C stdio functions. 

Because stdiobuf objects provide no buffering other than that 
provided by the C stdio functions, any changes to file attributes or 
contents made via a stdiobuf are reflected immediately in the stdio 
data structures. This includes file positioning using seekof f ( ) or 
seekpos ( ). For stdiobuf objects, the get and put pointers are tied 
together. That is, if you move one, you move the other. 

Unless you are mixing streambuf and stdio access to the same file, 
you should use class f ilebuf instead of class stdiobuf. Use of 
f ilebuf objects may improve performance. 


Parent Class class stdiobuf inherits characteristics from class streambuf. 

See the description of this parent class for the details on functions and 
operators that are inherited. 
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Constructors class stdiobuf defines one constructor: 

stdiobuf : : s tdiobuf ( FILE *file); 

creates a stdiobuf object associated with an open FILE*. 

Destructors The class stdiobuf destructor is 

virtual stdiobuf : :~stdiobuf () ; 
closes the associated file*, if opened. 

Non-Virtual Member The following descriptions detail the non-virtual member functions for 

Functions class stdiobuf. The redefined virtual functions are described later in 
this section. 

int stdiobuf :: is_open () ; 

returns a nonzero value if the stdiobuf is connected to an open file; 
returns 0 otherwise. 

FILE* stdiofile(); 

returns the associated FILE*. 

Virtual Member The following functions override their base class definitions (in class 
Functions streambuf). 

streampos stdiobuf :: seekoff ( streamoff offset, 
seek_dir place, int mode = ios : : in I ios : : out ) ; 

moves the get and/or put pointers of the streambuf. place can be 

one of the following: 

ios : : beg indicates the start of file. 

ios : : cur indicates the current get and put position. 

ios : : end indicates the end of file. 

offset is a positive or negative integer position relative to place, 
mode can be one of the following: 

ios : : in 

moves the get pointer, 
ios : : out 

moves the put pointer, 
ios : : in I ios : : out 
moves both pointers. 

Whether seekoff ( ) works for a stdiobuf depends on the 
characteristics of the associated FILE*. 
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streampos stdiobuf : : seekpos ( streampos pos, int mode 
= ios : : in I ios : : out ) ; 

moves the get and/or put pointers of the streambuf . 
pos must be a value returned by a previous call to seekof f ( ). 
mode can be one of the following: 
ios : : in 

moves the get pointer, 
ios : : out 

moves the put pointer, 
ios : : in I ios : : out 
moves both pointers. 

Whether seekpos ( ) works for a stdiobuf depends on the 
characteristics of the associated FILE*. 

Some stream buffers do not support seeking. For those stream buffers, 
seekpos ( ) returns streampos ( EOF ) to indicate an error occurred. 
See the documentation for specific stream buffer classes (such as 
f ilebuf) for more information on what kinds of seeking are allowed. 

virtual int stdiobuf :: sync () ; 

tries to force the state of the get or put pointer of the stdiobuf to 
be synchronized with the state of the associated file. This attempt at 
synchronization may result in the following: 

□ characters being written to the file, if some have been buffered for 
output. All characters may not be written immediately due to 
additional buffering performed by the operating system. 

□ an attempt to seek the file, if characters have been read and 
buffered for input. 

This function usually returns 0; if synchronization is not possible it 
returns EOF. 


See Also class stdiostream 



694 Chapter 8 


Class Streambuf Provide base class for all stream buffers 

Synopsis jfinclude <iostream.h> 

class streambuf 

{ 

public: 

int in_avail(); 
int out-waiting ( ) ; 

int sbumpc(); 
int sgetc(); 

int sgetn(char *s, int n); 
int snextc( ) ; 
void stossc( ) ; 

int sputbackc(char c); 

int sputc(int c ) ; 

int sputn(const char *s, int n); 

virtual int sync(); 

virtual streampos seekof f ( streamof f offset, seek_dir place, 
int mode = ios: : ini ios: :out) ; 
virtual streampos seekpos( streampos pos, 
int mode = ios: sin I ios: : out ) ; 

virtual streambuf* setbuf(char *p, size_t len); 

); 

Description class streambuf is declared in the iostream.h header file and is 
the base class for all stream buffers. Stream buffers manage the flow of 
characters between the program and the ultimate sources or consumers 
of characters, such as external files. The streambuf class defines 
behavior common to all stream buffers. More specialized classes can be 
derived from class streambuf to implement appropriate buffering 
strategies for particular stream types. For example, f ilebufs implement 
buffering suitable for file input or output and str streambuf s 
implement buffering suitable for transfer of data from strings in memory. 
A streambuf is almost never used directly (classes derived from it are 
used instead), but more often acts as an interface specification for derived 
classes. 

The functions defined by the streambuf interface are divided into 
two groups: non-virtual functions and virtual functions. These sets of 
functions are described separately. 
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class streambuf 

(continued) 

Constructors and 
Destructors 


Non-Virtual Member 
Functions 


Provide base class for all stream buffers 


class streambuf defines two constructors and one destructor. All 
these functions are protected. This ensures that class streambuf is 
used only as a base class for derived classes. 

The following list describes the non-virtual streambuf interface. 

int streambuf :: in_avail () ; 

returns the number of characters that have been buffered for input. 
That is, the number of characters that have been read from the 
ultimate source of the input but have not been extracted from the 
streambuf. Generally, this information is useful only for classes 
derived from class streambuf. 

Int streambuf :: out_waiting () ; 

returns the number of characters that have been buffered for output. 
That is, the number of characters that have been inserted into the 
streambuf, but have not been delivered to its ultimate destination. 
Generally, this information is useful only for classes derived from 
class streambuf. 
int streambuf :: sbumpc () ; 

advances the get pointer one character and returns the character 
preceding the advanced pointer. If the get pointer is at the end of the 
stream, the get pointer is not moved and EOF is returned, 
int streambuf : : sgetc( ) ; 

returns the character following the get pointer. This function does not 
move the get pointer. If the get pointer is at the end of the stream, 
this function returns EOF. 
int streambuf :: sgetn( char *s, int n) ; 

extracts the next n characters from the stream into s and positions 
the get pointer after the last extracted character. If there are less than 
n characters between the get pointer and the end of the stream, those 
characters are extracted into s and the get pointer is moved to the end 
of the stream. This function returns the number of characters 
extracted into s. 

int streambuf : : snextc ( ) ; 

advances the get pointer one character and returns the character after 
the advanced pointer. If the get pointer is at the end of the stream, the 
get pointer is not moved and EOF is returned. 

void streambuf :: stossc () ; 

advances the get pointer one character. 
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class streambuf 

( continued ) 


Virtual Member 
Functions 


Provide base class for all stream buffers 


int streambuf : : sputbackc ( char c ) ; 

backs the get pointer up one character, returning c. c must be the 
character that the get pointer is moved over; if it is not, the effects of 
this function are undefined. For example, if the get pointer is at the 
start of the stream and you call this function, the effect is undefined. 

Also, each class derived from streambuf may impose a limit on 
the number of characters that can be moved over by sputbackc( ). 
If you exceed this limit, this function returns EOF. For some classes, 
you cannot back up over any characters, 
int streambuf :: sputc ( int c); 

stores c in the position following the put pointer, replacing any pre- 
existing character, and then advances the put pointer one position. 
This function returns c if the operation is successful, or EOF if an 
error occurs. 

int streambuf :: sputn( const char *s, int n); 

stores after the put pointer the first n characters addressed by s, 
replacing any pre-existing characters in those positions, and then 
advances the put pointer past the last character stored. This function 
returns the number of characters successfully stored. 

The following virtual functions are members of class streambuf. 
These functions can be redefined in derived classes (both those supplied 
by the library and those you define yourself) to customize the behavior of 
streambuf objects. 

virtual int streambuf :: sync () ; 

tries to force the state of the get or put pointer of the streambuf to 
be synchronized with the state of the sink or source it is associated 
with. This function returns 0 if successful, or EOF if an error occurs. 
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Class Streambuf Provide base class for all stream buffers 
(continued) 

virtual streampos streambuf :: seekoff ( streamoff 
offset, seek_dir place, int mode = 
ios : : in I ios : : out ) ; 

moves the get and/or put pointers of the streambuf. place can be 

one of the following: 

ios : : beg indicates the start of file. 

ios : : cur indicates the current get or put position. 

ios : : end indicates the end of file. 

offset is a positive or negative integer position relative to place, 
mode can be one of the following: 

ios : : in 

moves the get pointer, 
ios : : out 

moves the put pointer, 
ios : : in I ios : : out 

moves both pointers. This is the default value. 

Some kinds of seeking are not supported for certain stream buffers. 
If a particular stream buffer does not support the seeking specified, 
this function returns streampos ( EOF ) to indicate an error 
occurred. See the documentation for specific stream buffer classes 
(such as filebuf)for more information on what kinds of seeking are 
allowed. 
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class streambuf 

(continued) 


Provide base class for all stream buffers 


virtual streampos streambuf :: seekpos ( streampos pos, 
int mode = ios : : in I ios : : out ) ; 

moves the get and/or put pointers of the streambuf. 
pos must be a value returned by a previous call to seekoff( ). 
mode can be one of the following: 

ios : : in 

moves the get pointer, 
ios : : out 

moves the put pointer, 
ios: :inlios: : out 

moves both pointers. This is the default value. 

Some stream buffers do not support seeking. For those stream 
buffers, seekpos ( ) returns streampos ( EOF ) to indicate an error 
occurred. See the documentation for particular stream buffer classes 
(such as filebuf) for more information on what kinds of seeking 
are allowed. 

virtual streambuf* streambuf :: setbuf ( char *p, size_t 
len ) ; 

allocates a buffer area to be used for buffering within the 
streambuf. 
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Class Provide string I/O 

strstreambuf 

Synopsis ((include <strstream.h> 

class strstreambuf : public streambuf 


public: 

strstreambuf ( ) ; 
strstreambuf ( int len); 

strstreambuf ( void* ( *a )( long) , void ( *f ) ( void* ) ) ; 
strstreambuf (char *b, int size, char *pstart = 0); 

~strstreambuf ( ) ; 


void freeze! int n = 1); 
char* str ( ) ; 


virtual streambuf* setbuf(char *p, size_t len); 
int sync( ) ; 

virtual streampos seekoff (streamoff offset, seek_dir place, 
int mode = ios: : in I ios: :out) ; 
virtual streampos seekpos ( streampos pos, 
int mode = ios: : in I ios: :out) ; 


) ; 


Description The header file strstream.h declares class strstreambuf, which 
specializes class streambuf to provide for I/O using arrays of char 
(strings). 

For strstreambuf objects, the get and put pointers are separate. 
That is, if you move one of these pointers you do not necessarily move 
the other. 

strstreambuf objects are created in one of two different modes, 
dynamic mode or static (fixed) mode. Once a strstreambuf is created 
it does not change modes. The following list explains the difference 
between fixed and dynamic mode: 

dynamic mode 

means the strstreambuf does not have a fixed size and grows as 
needed. When the array associated with a dynamic mode 
strstreambuf is filled, the strstreambuf automatically allocates 
a larger array, copies the old smaller array to the larger, and frees the 
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Class Provide string I/O 

strstreambuf 

( continued ) 

smaller array. The functions used to handle allocating and freeing the 
arrays are determined by the constructor used to create the 
strstreambuf (see the description of the constructors later in this 
section). 
static mode 

means the strstreambuf has a fixed size that does not change. If 
the array associated with a static mode strstreambuf is filled, 
further writes to the strstreambuf may corrupt memory. Be 
cautious when inserting into static mode strstreambuf s. 

Note: Do not confuse static mode with the static storage class 
modifier. 

class strstreambuf defines some member functions of its own 
and also redefines several virtual functions from the base class. 

Parent Class class strstreambuf inherits characteristics from class 

streambuf . See the description of this parent class for the details on 
functions and operators that are inherited. 

Constructors class strstreambuf defines four constructors: 

strstreambuf : : strstreambuf ( ) ; 

creates an empty strstreambuf object in dynamic mode, 
strstreambuf : : strstreambuf ( int len ) ; 

creates an empty strstreambuf object in dynamic mode. The initial 
allocation uses at least len bytes. 

strstreambuf : : strstreambuf ( void* ( *a ) ( long ) , void 
( *f ) ( void* ) ) ; 

creates an empty strstreambuf object in dynamic mode, a is the 
allocation function to be used to do the dynamic allocation and takes 
as its argument a long, which specifies the number of bytes to 
allocate. If a is NULL, the operator new is used instead of a. 

f is the deallocation function, which frees the space allocated by a. 
f takes as its argument a pointer to an array allocated by a. If f is 
NULL, the operator delete is used instead of f . 
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class 

strstreambuf 

(continued) 


Destructors 


Non-Virtual Member 
Functions 


Provide string I/O 


strstreambuf :: strstreambuf ( char *b, int size, char 
*pstart = 0 ) ; 

constructs a strstreambuf object in static mode; it does not grow 
dynamically, b specifies where to start the array and size specifies 
the size of the array, as explained in the following list. 

□ If size is positive, the array is size bytes long. 

□ If size is 0, the function assumes b points to the start of a null- 
terminated string. In this case, the string, not including the \ 0 
character, is considered to be the strstreambuf. 

□ If size is negative, the strstreambuf is assumed to be 
indefinitely long. 

The get pointer receives the value of b and the put pointer receives 
the value of pstart. If pstart is NULL, then storing characters in 
the strstreambuf is not allowed and causes the function to return 
an error. 

class strstreambuf defines one destructor: 

strstreambuf : :~strstreambuf ( ) ; 

closes the strstreambuf object. The destructor causes any memory 
allocated for the strstreambuf to be freed. 

class strstreambuf defines two non-virtual member functions. 

void strstreambuf :: freeze ( int n = 1); 

controls the automatic deletion of the array. If n is nonzero, which is 
the default, the array is not deleted automatically. If n is 0, the array 
is unfrozen and is deleted automatically. The array is deleted 
whenever a dynamically created strstreambuf needs more space or 
when the destructor is called. This function only applies to 
dynamically created strstreambuf s, it has no effect on statically 
created strstreambuf s. 

If you try to store characters in a frozen array, the effect is 
undefined. 

char* strstreambuf : :str( ) ; returns a pointer to the first 
character in the current array and freezes the array. After str ( ) has 
been called, the effect of storing characters in the array is undefined until 
the strstreambuf is unfrozen by calling freeze ( 0). 
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strstreambuf 

( continued ) 

Virtual Member class strstreambuf redefines several virtual functions from its base 
Functions class (class streambuf ). 

virtual strstreambuf :: streambuf * setbuf(char *p, 
size_t len) ; 

tells the strstreambuf that the next time an array is dynamically 
allocated it should be at least len bytes long, p is ignored, 
int strstreambuf :: sync () ; 
returns EOF. 

virtual streampos strstreambuf :: seekof f ( streamof f 
offset, seek_dir place, int mode = 
ios : : in I ios : : out ) ; 

moves the get and/or put pointers of the strstreambuf. See the 
description of streambuf : : seekof f ( ) for explanations of 
offset, place, and mode. 

If the strstreambuf is in dynamic mode, this function returns 
streampos ( EOF ) to indicate an error occurred. 

If either the get or put pointer is moved to a position outside the 
strstreambuf, or if the put pointer is moved for a 
strstreambuf that does not allow output, then streampos (EOF) 
is returned and the pointers are not moved. 

Ifplaceisios:: end, it refers to the end of the array, 
virtual streampos strstreambuf :: seekpos ( streampos 
pos, int mode = ios : : in I ios : : out ) ; 

moves the get and/or put pointers of the strstreambuf. 

If the strstreambuf is in dynamic mode, this function returns 
streampos ( EOF ) to indicate an error occurred. 

pos must be a value returned by a previous call to seekoff( ). 

See the description of streambuf : : seekpos ( ) for an 
explanation of mode. If ios : : out is specified for mode and output 
is not allowed for this strstreambuf, then streampos ( EOF ) is 
returned to indicate an error occurred and the put pointer is not 
moved. 

See Also class strstream 
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Manipulator 

Class 

Descriptions 


This section describes the contents of the iOMANlP.h header file, which 
provides predefined manipulators, as well as support functions and 
classes that enable you to create your own manipulators. 
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class IOMANIP Provide manipulators 
Synopsis S include <iomanip.h> 


#def ine 

SHANIP(T) 

— smanip_ 

SS T 

Sdef ine 

SAPP(T) 

— sapp_ SS 

T 

#def ine 

IMANIP(T) 

imanip_ 

SS T 

Sdef ine 

IAPP(T) 

— iapp_ SS 

T 

Sdef ine 

OMANIP(T) 

oraanip_ 

SS T 

Sdef ine 

OAPP(T) 

— oapp_ SS 

T 

Sdef ine 

IOMANIP (T) 

iomanip_ 

■ SS ' 

Sdef ine 

IOAPP(T) 

— ioapp_ SS T 

Sdef ine 

IOMANIPdeclare(T) 



IOMANIPdeclare( int) ; 
IOMANIPdeclare( long) ; 


class SMANIP(T) 

( 

public: 

SMANIP (T)(iosS(*f)(ios&, T), T d ) ; 

friend istreamS operator »(istreamS i, SMANIP(T)6 m) ; 
friend ostreamS operator <<(ostream6 o, SMANIP(T)8 m); 

) ; 

class SAPP(T) 

( 

public: 

SAPP(T) (i0S6(*f ) (i0S6, T ) ) ; 

SMANIP(T)operator ( ) (T d); 

); 


Class IMANIP(T) 

( 

public: 

IMANIP(T) (i0S6(*f ) (ios£, T), T d ) ; 

friend istreamfi operator »(istream£ i, IMANIP(T)S m) ; 

1; 

class IAPP(T) 

( 

public : 

IAPP(T)(ios8(*f)(ios6, T ) ) ; 
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class IOMANIP Provide manipulators 
( continued ) 

IMANIP ( T ) operator ( ) ( T d); 

); 

class OMANIP(T) 

{ 

public: 

OMANIP (T)(iosg(*f)(ios6, T), T d); 

friend ostreamg operator <<(ostream6 o, 0MANIP(T)6 m) ; 

); 

class OAPP(T) 

( 

public: 

OAPP(T) (ios6(*f)(ios&, T ) ) ; 

OMANIP(T)operator( ) (T d); 

); 

class IOMANIP(T) 

( 

public: 

IOMANIP(T) (iOS6(*f ) (ios6, T), T d) ; 

friend istreamg operator >>(istream6 i, IOMANIP(T) 6m) ; 
friend ostreamg operator <<(ostream6 o, I0MANIP(T)6m) ; 

); 

class IOAPP(T) 

( 

public: 

IOAPP (T)(ios6(*f)(ios6, T)); 

IOMANIP ( T ) operator ( ) ( T d ) ; 

} ; 

SMANIP(int) setw(int width); 

SMANIP(int) setfill(int fill_char); 

SMANIP(int) setprecision(int precision); 

SMANIP(long) setiosf lags(long flags); 

SMANIP(long) resetiosflags(long flags); 

Description The IOMANIP . h header file declares some predefined manipulators, as 
well as support functions and classes that enable you to create your own 
manipulators. A manipulator is a value that can be used to effect some 
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class IOMANIP 

(continued) 


Predefined 

Manipulators 


Provide manipulators 


change to a stream by inserting it into or extracting it from the stream. 
For example the flush function is a manipulator of os tr earn objects: 

cout << flush; // Causes cout to be flushed. 

In fact, any function of one the following types is a manipulator: 

ostreamS (ostreamS) 

is a manipulator for os tr earn objects. 
istreamS (istreamS) 

is a manipulator for i stream objects. 
iosS ( ios 6 ) 

is a manipulator for i stream or os tr earn objects. 

You can also create manipulators that have arguments. The IOMANIP . h 
header file defines two manipulator-creation classes for each type of 
stream (ios, istream, ostream, and iostream). One class has a 
name in the form xMANIP ( T ) and the other class has a name in the 
form xAPP ( T ) , where T is an identifier that names a type (such as a 
typedef name for a class name) and x is a letter such as S. 

For ios objects, these two classes are named SMANIP(T) and 
SAPP(T). 

The predefined manipulators defined by IOMANIP . h allow you to control 
various pieces of the format state of a stream. These manipulators are 
described in the following list. 

SMANIP(int) setw(int w) 

returns a manipulator (an S man ip ( int ) ) that can be used to set the 
width ( ) value of an ios object. 

SMANIP ( int ) setf ill ( int f) 

returns a manipulator that can be used to set the f i 1 1 ( ) value of an 
ios object. 

SMANlP(int) setprecision( int p) 

returns a manipulator that can be used to set the precision( ) 
value of an ios object. 

SMANIP(long) setiosf lags ( long flags) 

returns a manipulator that can be used to set the f lags ( ) value of 
an ios object. 
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class IOMANIP 

( continued ) 


Examples Using 
Predefined 
Manipulators 


User-Defined 

Manipulators 


Provide manipulators 


SMANIP(long) resetiosf lags ( long flags) 

returns a manipulator that can be used to reset the f lags ( ) value of 
an ios object. 

The following example transmits ********27,00048: 

cout << setw(10) << set f ill ( ' * ' ) << 27 << << setw(5) 

« setf ill ( ' 0 ' ) << 48; 

The following example transmits 32,5: 

cout << setprecision(2) << 32.1 << 

<< setprecision( 0 ) << 5.3; 

The following example sets the skipws bit in cout‘s format state: 

cout « setiosflags(ios: rskipws) 

The following example clears the skipws bit in cout's format state: 

cout << resetiosflags(ios: :skipws) 

As well as the predefined manipulators described in the previous section, 
the IOMANIP . h header file also provides the means for you to create 
your own manipulators. It does this by defining a macro, 

I OMANI Pde cl are ( T ) that when invoked with a typedef name for T 
declares the following classes: 

SMANIP(T) and SAPP(T) 
are for use with ios objects. 

I man IP ( T ) and IAPP(T) 

are for use with i stream objects. 

OMANIP ( T ) and OAPP ( T ) 

are for use with os tr earn objects. 

IOMANIP ( T ) and IOAPP(T) 

are for use with ios tr earn objects. 

class SMANIP ( T ) and SAPP ( T ) are explained in detail in this 
section; the other classes are very similar to SAPP ( T ) and only the 
differences between them and class SMANIP and SAPP(T)are noted. 
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Class IOMANIP Provide manipulators 
(continued) 


If you are going to create new manipulators using the various 
xMANIP ( T ) and xAPP ( T ) classes, the classes must first be defined for a 
particular type name. This is done by putting the following definition in 
any module that uses the xMANIP ( T ) or xAPP ( T ) classes for a 
particular type name: 

IOMANIPdeclare ( type-name ) ; 

where type-name can be any valid type identifier. Because int and long 
are the most commonly used type names in manipulators, the 
iOMANiPdec lares for these type names are included in the 
IOMANIP . h header file and your program should not declare them 
again. If you need to create manipulators using the xMANIP ( T ) and 
xAPP(T) classes for type names other than int or long, you must 
include a use of IOMANIPdeclare ( ) in your module. 

For example, before using xMANIP (T) and xAPP(T) classes to create 
manipulators that accept char arguments, the xMANIP(T) and 
xAPP ( T ) classes for the type name char must be declared as follows: 

((include <I0MANIP.h> 

IOMANIPdeclare ( char ) ; 

If you need to create manipulators that accept arguments of more 
complicated types, like char* arguments, you must first declare a 
typedef for the type, because IOMANIPdeclare requires a single- 
word type name. For example: 

((include <I0MANIP.h> 
typedef char* STRING; 

IOMANIPdeclare ( STRING) ; 

class SMANIP(T) 

provides a constructor and two operators, as detailed next. 

SMANIP(T) (iOS6(*f ) (ioss, T), T d) 

constructs an SMANIP(T) and returns a single argument manipulator 
by collecting the function f and argument d into a single manipulator 
value. It is assumed that f is a function that changes i o s in some 
way using the value of d. 
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( continued ) 


friend istreamS operator >> (istreamS i, SMANIP(T)S 
m) 

friend ostreamS operator << (ostreamS o, SMANIP(T)S 
m) 

enable SMANIP(T) objects to be inserted into is tr earn objects and 
extracted from os tr earn objects, respectively. They each use the 
values f and d from the SMANIP(T) value. They then call 
f (myios ,d) where myios is the ios part of i or o, respectively. It 
is assumed that f is a function that changes ios in some way using 
the value of d. 

It is often easier to create manipulators using the applicator classes, 
in this case SAPP ( T ) , than to use the xMANiP ( T ) classes, 
class SAPP ( T ) is described next. 

class SAPP(T) 

provides a constructor and an operator, as detailed next. sapp(T) 
objects make it easier to use s man IP ( T ) objects. The Examples section 
gives an example of using an SAPP ( T ) object. The members of 
class SAPP(T) are: 

SAPP(T) ( iosS ( *f ) ( iosS , T ) ) 

initializes an SAPP(T) object to contain f. 

S MAN IP ( T ) operator ( ) (T d) 

creates and returns an S MAN IP ( T ) object using the f from the 
SAPP ( T ) and the d argument. 

Other manipulator classes 

The rest of the classes defined by iOMANlPdeclare ( T ) are similar to 
class SAPP(T), with the following differences: 

□ for imanip ( T ) and IAPP ( T ) , f has type 
istreamS ( *f ) ( istreamS , T) 

□ for OMANIP ( T ) and OAPP ( T ) , f has type 
ostreamS ( *f ) ( ostream& , T) 

□ for IOMANIP ( T ) and IOAPP(T), f has type 
iostreamS ( *f ) ( iostreamS , T) 

□ IMANIP ( T ) does not contain operator << 

□ OMANIP ( T ) does not contain operator >> 
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class IOMANIP Provide manipulators 
( continued ) 

Examples of User- The following code creates a manipulator setwidth, which works like 
Defined Manipulators the library’s setw. 

ios£ setw_func( iosS i, int w) 

l 

i .width(w) ; 
return i; 


SAPP (int) setwidth ( setw_func ) ; 
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clib subdirectory 25 
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clog stream 622 
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example 617 

syntax and description 615-616 
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compression of header files 27-28 
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enum format-state, class ios 646-647 
conversion functions 
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cos function 173 
cos() function 612-614 
cosh function 174 
cosh() function 612-614 
cot function 175 
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creat function 176 
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ctime function 177-178 
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restrictions in global symbol tables (GSTs) 31 
data = far compiler option 14, 17 
data=faronly compiler option 14 
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daytbl data name 67 

_dclose function 183 
—dcreat function 184 
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class ios 643, 646 
formatting C+ + I/O 627 
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rules for initializing libraries 9 
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devices 
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compared with libraries 59 
creating custom devices 59 
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diagnostic control functions 
assert 142-143 
except 207-208 
perror 371 
poserr 372 
strerror 514 

matherr 333-334 
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directories 

correlation between header file directories and library 
directories 24 
devs: 1 
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subdirectories in include: directory 25 
directory functions 
chdir 159 
closedir 171 
dfind 186-187 
dnext 192-193 
findpath 230-231 
getcd 279 
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directory functions (continued) 
getcwd 283 
getfnl 289-291 
getpath 295 
mkdir 348 
opendir 368-369 
readdir 393 
rewinddir 403 
rmdir 406 
seekdir 414 
telldir 566 
div function 190-191 
dnext function 192-193 
_dopen function 194 
dos_packet function 195 
DOSBase data name 68 
dqsort function 196 
drand48 function 197 
—dread function 198 
—dseek function 199 
—dwrite function 200 
dynamic mode, class strstreambuf 699-700 
DO register 54, 55 

E 

ecvt function 201-202 

emit function 203 
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function description (.fd) file 41 
end seek— dir flag 654 
endl manipulator 
class ios 643 
class ostream 677 
formatting C+ 4- I/O 628 
ends manipulator 
class ios 644 
class ostream 678 
formatting C + + I/O 628 
enum format— state, class ios 645-649 
conversion base flags 646-647 
examples 649 
floating-point flags 647-648 
format flags 646-648 
formatting functions 648 
padding flags 646 
syntax and description 645-646 
enum io_ state, class ios 650-651 
I/O state flags 650-651 


I/O state functions 651 
syntax and description 650 
enum open— mode, class ios 652-653 
open— mode flags 652-653 
syntax and description 652 
enum seek— dir, class ios 654 
eof() function 651 
eofbit flag 650 
—EPILOG function 204-205 
erand48 function 206 
errno data name 69-71 
error codes 

_ FPERR data name 74 
_ OSERR data name 91-94 
error handling functions 
clearerr 167 
clrerr 172 
feof 219 
ferror 220 

except function 207-208 
exclamation point (!) operator 
converting ios object to 0 651 
testing streams for errors 628 
exec.library 7 
exit function 209-210 
— exit function 211 
exp function 212 
exp() function 610-611 
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description of formatted input functions 658-660 

extracting characters 623-624 

overloading 624 

synopsis for class istream 656 

working with complex numbers 618-619 
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fabs function 213 
fail() function 651 
failbit flag 651, 659 
fclose function 214 
fcloseall function 215 
fcvt function 216-217 
.fd file 

See function description (.fd) file 
fdopen function 218 
fd2pragma utility 40-42 
See also function description (.fd) file 
creating .fd file 40-41 
running 41 
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feof function 219 
ferror function 220 
fflush function 221 
FFP 

See Motorola Fast Floating-Point (FFP) format 
fgetc function 222 
fgetchar function 223 
fgetpos function 224-226 
fgets function 227-228 
file control functions 
close 170 
creat 176 
_ dclose 183 
_dcreat 184 
—dcreatx 185 
_dopen 194 
fclose 214 
fcloseall 215 
fdopen 218 
fflush 221 
fileno 229 
flushall 233 
fmode 235 
fopen 236-240 
freopen 263 
iomode 304 
mkstemp 349-350 
mktemp 351-352 
open 366-367 
setbuf 415 
setnbf 421 
setvbuf 422-423 
tmpfile 571-572 
tmpnam 573 
file management functions 
access 134-135 
chkufb 164 
chmod 165—166 
fileno 229 
fmode 235 
fstat 270-271 
getfa 288 
getft 292 
iomode 304 
remove 396-397 
rename 398-399 
setbuf 41 5 
setnbf 421 
setvbuf 422-423 
stat 439-440 
stcgfe 448-449 


stcgfn 450 
stcgfp 451-452 
strmfe 523 
strmfn 524-525 
strmfp 526 
strsfn 541-542 
unlink 581-582 
file positioning functions 
_dseek 199 
fgetpos 224—226 
fseek 268 
fsetpos 269 
ftell 272 
lseek 323-324 
rewind 402 
tell 565 
filebuf class 
See class filebuf 
filebuf() constructor 688 
filebuf() destructor 688 
fileno function 229 
fiU() function 627, 642, 673 
findpath function 230-231 
fixed floating-point flag 647, 675 
flags() function 648 
flibcall #pragma statement 
calculating magic value 38, 39 
format 36 
purpose 34 
floatfield member 648 
floating-point flags 
class ostream 675 

enum format-state, class ios 647-648 
floating-point numbers 

IEEE format used in scm.lib 18 
Motorola Fast Floating-Point (FFP) format 18 
floor function 232 
flush manipulator 
class ios 644 
class ostream 678 
formatting C+ + I/O 627 
flush() function 
class ostream 677 
purpose and use 625 
flushall function 233 

fmask data name 72 

fmod function 234 

fmode data name 73 

fmode function 235 
fopen function 
APPEND mode 237 
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fopen function (continued) 

CREATE mode 236 
description 236-240 
example 239-240 
portability 239 
READ mode 236 
returns 239 
synopsis 235 
TRANSLATE mode 237 
TRUNC mode 236 
values specified by mode strings 238 
WRITE mode 237 
FORKENV structure 242 
forkl, forkv functions 
description 241-244 
example 244-247 
FORKENV structure 242 
portability 244 
process ID structure 243 
returns 244 
synopsis 241 

TermMsg structure 242-243 
format flags 
class ostream 675-676 
enum format-state, class ios 646-648 
formatted I/O, C+ + 627-628 
See also enum format-state, class ios 
bitalloc() function 643 
built-in manipulators 627-628, 643-644 
class ios functions 627, 641-643 
dec manipulator 627, 643, 646 
endl manipulator 628, 643, 677 
ends manipulator 628, 644, 678 
fill() function 627, 642, 673 
flush manipulator 627, 644, 678 
format flag functions 641-642 
hex manipulator 627, 643, 646 
iword() function 643 
oct manipulator 643, 646 
precision() function 627, 642 
pword() function 643 
user-defined format flag functions 642-643 
width() function 627, 642, 673, 674 
ws manipulator 627, 643 
xalloc() function 643 
formatted I/O functions 
fprintf 248-253 
fscanf 265-267 
printf 373-374 
scanf 409 
sprintf 429-430 


sscanf 435 
vfprintf 592-593 
vprintf 594-595 
vsprintf 596-597 

formatted input functions, class istream 658-660 
formatted output functions, class ostream 673-676 
formatting functions, enum format-state (class ios) 
_ FPERR data name 74-75 
fpos() function 683 
fprintf function 
description 248-253 
example 253—254 
format of specification 248-253 
portability 253 
returns 253 
synopsis 248 
fputc function 255 
fputchar function 256 
fputs function 257 
fqsort function 258 
fread function 259 
free function 260-262 
freeze{) function 701 
freopen function 263 
frexp function 264 
fscanf function 
description 265-267 

format of conversion specification 265-267 
portability 267 
returns 267 
synopsis 265 
fseek function 
See also seekoff() function 
syntax and description 268 
fsetpos function 
See also seekpos() function 
syntax and description 269 
fstat function 270-271 
fstream class 
See class fstream 
fstream() constructor 632 
fstream() destructor 632 
ftell function 272 
function description (.fd) file 
commas for separating arguments 41 
creating for #pragma statements 40 
creating for C++ shared libraries 54-55 
example 40 

format for entry points 41 
slashes (/) for separating registers 41 
##base instruction 40, 49 
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##end instruction 41 
## private instruction 41 
##public instruction 40 
functions 

See library functions 
fwrite function 273 


G 

.gadget files 
library bases 11 
gadgets subdirectory 25 
gcount() function 662 
gcvt function 274 
general utility macros and functions 
geta4 275 
getreg 296-297 
isatty 307 
offsetof 360-361 
ovlyMgr 370 
putreg 383 

emit 203 

get pointer 

moving with seekoff() function 692, 697, 702 
moving with seekpos() function 693, 698, 702 
purpose and use 626 
setting with seekoff() function 688 
setting with seekpos() function 689 
synchronizing with sync() function 693, 696 
get() function 
class istream 661 
purpose and use 625 
getasn function 276-277 
geta4 function 275 
getc function 278 
getcd function 279 
getch function 280 
getchar function 281 
getclk function 282 
getcwd function 283 
getdfs function 284-285 
getenv function 286-287 
getfa function 288 
getfnl function 289-291 
description 289-290 
example 290-291 
portability 290 
returns 290 
synopsis 289 
getft function 292 


getlinef) function 
class istream 661 
purpose and use 625 
getmem function 293 
getml function 294 
getpath function 295 
getreg function 296-297 
gets function 298-299 
GfxBase data name 76 
global data in libinit.c file 45 
global symbol tables (GSTs) 29-31 
creating 30 

difference from Version 5 precompiled header files 29 
header file restrictions 31 
purpose 29 

specifying with gst compiler option 30 
global symbols 
NEWDATAL 52 
RESLEN 52 

LibID 52 

LibName 52 

global variables 7 

gmtime function 300-301 

good() function 651 

goodbit condition 650 

gst compiler option 30 

gstimmediate compiler option 29 

GSTs 

See global symbol tables (GSTs) 


H 

.h filename extension for header files 21 
halloc function 302 
hardware subdirectory 25 
header files 21-31 
available headers 22-25 
C++ functions 23 
compressing 27-28 

correlation between header file directories and library 
directories 24 
definition 21 

determining which headers to use 26-27 

including ^pragma statements 6 

including all files for Amiga system libraries 6-7 

including function prototypes 22 

iostream.h 622 

library bases for .library files 9-10 

library bases for files other than .library files 11 

located in sc:include and sc:cxxinclude directories 22 
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header files (continued) 
new.h 605 
proto/all.h 7 
proto/exec.h 7 
purpose and use 21-22 
search path for include files 25-26 
shared libraries 23-25 
standard C functions 23 
stream.h 629-630 
using built-in functions 28-29 
using global symbol tables (GSTs) 29-31 
hex conversion base flag 646, 675 
hex manipulator 
class ios 643, 646 
formatting C+ + I/O 627 


.i filename extension for assembler header files 21 
I/O classes 

buffer class descriptions 686-702 
manipulator class descriptions 703-710 
naming conventions 622 
stream class descriptions 631-685 
I/O functions 
block I/O functions 123 
character I/O functions 123 
error handling functions 124 
file control functions 125 
file positioning functions 126 
formatted I/O functions 124 
standard I/O functions 122 
string I/O functions 123 
I/O state flags 628 

I/O state functions, enum io_state (class ios) 651 
iabs function 303 

IEEE format for floating-point numbers 18 
IEEE shared math libraries (Commodore) 18 
ifstream class 
See class ifstream 
ifstream() constructor 636 
ifstream() destructor 637 
ignore() function 662 
imag() function 609 
in open_mode flag 652 
in_avail() function 695 
#include < proto/all.h > statement 7 
include files 
See header files 


include: directory 
location of header files 22 
subdirectories 25 
include:proto directory 6 
inheritance relationships between classes 622-623 
initialization code in custom shared libraries 45, 46 
input prefix function, class istream 658 
input stream 624 
insertion << operator 

description of formatted output functions 673-676 
inserting characters 623-624 
overloading 624 
synopsis for class ostream 671 
working with complex numbers 618-619 
internal padding 674 
internal padding flag 646 
IntuitionBase data name 77 
io_state enumerators 650-651 
IOMANIPdeclare(T) macro 707, 708 
iomode function 304 
ios class 


See class ios 


ios() constructor 

641 

ios() destructors 

641 

ios manipulator 

706 

iostream class 



See class iostream 
iostream.h header file 622 
iostream() constructor 655 
ipfx() function 658 
is.... functions 305—306 
is_open() function 
class filebuf 688 
class stdiobuf 692 
isatty function 307 
istream class 

See class istream 
istream() constructor 658 
istream() destructor 658 
istream manipulator 706 
istrstream class 
See class istrstream 
istrstream() constructor 664 
istrstream() destructor 664 
iword() function 643 
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J 

JOIN command (AmigaDOS) 
creating custom linkable library 43 
disadvantages 43 
jrand48 function 308 
jump table 52 


L 

labs function 309 

lcong48 function 310 

ldexp function 311 

ldiv function 312-313 

leading padding 674 

left padding (trailing padding) 674 

left padding flag 646 

.lib extension 

naming custom linkable libraries 42 
required for linkable libraries 1, 43 
libcall #pragma statement 
accessing functions in exec.library 7 
calculating magic value 38, 39 
format 35 
purpose 34 
LibClose function 51 
libcode compiler option 47, 50 
LibExpunge function 51 

LibFuncTab symbol 52 

LibID global symbol 52 

Liblnit function 50 
libinit.c file 45 
libinit.o module 

communication with slink command 52 
creating C+ + shared libraries 55 
effect on Liblnit function 50 

effect on LibOpen, LibClose, and LibExpunge functions 
51 

restrictions on shared libraries 45 
specifying with sc command 47 
libinitr.o module 

creating C+ + shared libraries 55 
creating shared libraries 46 

effect on LibOpen, LibClose, and LibExpunge functions 
51 

restrictions on shared libraries 45 
specifying with sc command 47 

Libmergeddata symbol 50 

LibName global symbol 52 

LibOpen function 51 


libraries 

See linkable libraries 
See shared libraries 
libraries subdirectory 25 
library bases 7-11 
automatic initialization 8 
automatic termination 8 
case sensitivity 9 
.class files 11 
defining 7-9 
.device files 11 
.gadget files 1 1 
initializing 7-9 

initializing for custom shared libraries 49 
.library files 9-10 
.resource files 11 
revision numbers 8, 89 
storing in global variable 7 
.library extension 

naming custom shared libraries 42 
required for shared libraries 1 
.library files 
library bases 9-10 
rules for initializing libraries 8 
stored in libs: directory 1 
library functions 
block I/O functions 123 
built-in functions 130 
calling in custom libraries 44, 49 
character I/O functions 123 
character-type macros and functions 111-112 
conversion functions 114-115 
diagnostic control functions 121 
directory functions 128 
error handling functions 124 
file control functions 125 
file management functions 126-127 
file positioning functions 126 
formatted I/O functions 124 
functions the user can replace but not call 130 
general utility macros and functions 117 
headers for C+ + functions 23 
headers for standard C functions 23 
I/O functions 123-126 
localization functions 128 
mathematical macros and functions 116-117 
memory allocation functions 120 
memory manipulation functions 120-121 
multibyte character functions 129 
program control functions 119 
random-number generation functions 118 
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library functions (continued) 
replacing with user-written functions 33-34 
screen control functions 129 
sorting functions 118 
string functions 112—113 
string I/O functions 123 
system interface functions 127 
time functions 121-122 
varying-length argument list macros 117 
link compiler option 15-16 
linkable libraries 2-3, 13-19 
See also linkable libraries, creating 
choice of options for linking with libraries 16-17 
compiling with correct library 14-15 
definition 1 

determining which library to use 13-14 
format of names for SAS/C libraries 13—14 
linking with correct library 15-17 
math libraries 17-19 

replacing functions with user-written functions 33-34 

sc.lib 2 

scm.lib 2 

scmffp.lib 3 

scmieee.lib 3 

scmnb.lib 3 

scms.lib 3 

scm881.1ib 3 

scnb.lib 3 

scs.lib 3 

scsnb.lib 3 

some combinations of compiler options not supported 14 
standard libraries 2 
support for registerized parameters 3 
linkable libraries, creating 43-44 
calling functions 44 
naming with .lib extension 42 
steps for creating 43 
when to create 42 
linker 

See slink command 
LinkerDB symbol 50 
linking programs 
See programs, linking 
localeconv function 314-315 
localization functions 
localeconv 314-315 
readlocale 394 
setlocale 418-419 
strcoll 510 
strxfrm 557-558 
localtime function 316 


log function 317 
log() function 610-611 
log 10 function 318 
long() function 683 
longjmp function 319 
avoiding in C + + programs 603 
avoiding in custom shared libraries 45 
syntax and description 319 
lqsort function 320 
lrand48 function 321 
lsbrk function 322 
lseek function 323-324 
Istat function 325-326 


M 

macros 

character-type macros and functions 111—112 
general utility macros and functions 117 
mathematical macros and functions 116-117 
varying-length argument list macros 117 
magic value for #pragma statements, calculating 38-40 
examples 39-40 

hexadecimal numbers for registers 38 
main function 
description 328 
example 329-330 
portability 329 
returns 328-330 
synopsis 328 
— main function 327 
makegst compiler option 30 
malloc function 331-332 
mangled names 55, 56 
manipulating complex numbers 
See class complex 
manipulator class 
See class IOMANIP 
manipulators 

built-in manipulators 627-628, 643-644 

creating manipulators with arguments 706 

creating user-defined manipulators 707-710 

dec 627, 643, 646 

definition 627, 705-706 

endl 628, 643, 677 

ends 628, 6.44, 678 

flush 627, 644, 678 

formatting C+ + I/O 627-628 

hex 627, 643, 646 

ios 706 



istream 706 
oct 643, 646 
ostream 706 
predefined 706-707 
predefined, examples 707 
resetiosflagsQ 707 
setfillO 706 
setiosfiags() 706 
setprecision() 706 
setw() 706 
ws 627, 643 
math libraries 1 7-1 9 
mutually exclusive libraries 14 
scm.lib 18 
scmffp.lib 18 
scmieee.lib 18 
scmnb.lib 19 
scms.lib 18 
scm881.1ib 19 
using math libraries 17-19 
MathBase data name 78 
mathematical macros and functions 
abs 133 
acos 136 
asin 141 
atan 146 
atan2 147 
ceil 158 
cos 173 
cosh 174 
cot 175 
div 190-191 
exp 212 
fabs 213 
floor 232 
fmod 234 
frexp 264 
iabs 303 
labs 309 
ldexp 311 
ldiv 312-313 
log 317 
log 10 318 
max 335 
min 347 
modf 355-356 
pow 375 
pow2 376 
sin 426 
sinh 427 
sqrt 432 


tan 563 
tanh 564 

math =ffp compiler option 15,18 
math =ieee compiler option 15 
math = standard compiler option 15, 18 
MathTranBase data name 79 
math=68881 compiler option 15, 19 

matherr function 333-334 

max function 335 
mblen function 336 
mbstowcs function 337 
mbtowc function 338 

member functions for stream classes 625-626 
memccpy function 339 
memchr function 340 
_MemCleanup function 341 
memcmp function 342 
memcpy function 343 
memmove function 344-345 
memory allocation functions 
bldinem 154 
calloc 156-157 
chkml 163 
free 260-262 
getmem 293 
getml 294 
halloc 302 
lsbrk 322 
malloc 331-332 
—MemCleanup 341 
rbrk 391 
realloc 395 
rlsmem 404 
rlsml 405 
rstmem 407 
sbrk 408 
sizmem 428 

memory management from C+ + programs 605 
memory manipulation functions 
memccpy 339 
memchr 340 
memcmp 342 
memcpy 343 
memmove 344-345 
memset 346 
movmem 357 
repmem 400-401 
setmem 420 
swmem 561 
memset function 346 
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—MeinType data name 
description 80-81 
mnemonics 80 
min function 347 
mkdir function 348 
mkstemp function 349-350 
mktemp function 351-352 
mktime function 353-354 
modf function 355-356 

montbl data name 82-83 

— months data name 84-85 
Motorola Fast Floating-Point (FFP) format 18 
movmem function 357 
mrand48 function 358 
—msflag data name 86 
msg #pragma statement 35 
—MSTEP data name 87 
multibyte character functions 
mblen 336 
mbstowcs 337 
mbtowc 338 
wcstombs 599 
wctomb 600 


N 

near data 

creating custom shared libraries 44 
libraries that copy near data section 45 
memory limitations for shared libraries 45 
new operator 605, 623 
new.h header file 605 
new-handier function 605 
NEWDATAL global symbol 52 
nocreate open_mode flag 653 
noreplace open_mode flag 653 
norm() function 609 
nostackcheck compiler option 47 
nrand48 function 359 
— nufbs data name 88 


o 

.o extension 

required for creating linkable libraries 43 
object module 42 
Object Module Librarian (OML) 

See also oml command 


advantages 43 

creating linkable libraries 42, 43 
oct conversion base flag 646, 675 
oct manipulator 643, 646 
offsetof function 360-361 
ofstream class 
See class ofstream 
ofstream() constructor 667 
ofstream() destructor 668 
oml command 

creating custom linkable library 43 
onbreak function 362-363 
onexit function 364-365 
open function 366-367 
open() function 
class filebuf 688 
class fstream 633 
class ifstream 637 
class ofstream 668 

open_mode flags, enum open_mode (class ios) 652-653 
OpenDevice function 8 
opendir function 368-369 
OpenLibrary function 
called by autoinitialization code 8 
calling before accessing custom libraries 42 
initializing library base 49 
interaction with LibOpen function 51 
OpenResource function 8 
operators, complex 
See complex operators 
operators, I/O 

checking status of ios object 628, 651 
extraction 618 
insertion 618 
opfx() function 673 
—OSERR data name 
AmigaDOS 2.0 error codes 93-94 
description 91 
osfx() function 673, 674 

oslibversion data name 89-90 

ostream class 
See class ostream 
ostream() constructor 672 
ostream() destructor 672 
ostream manipulator 706 
ostrstream class 
See class ostrstream 
ostrstream() constructor 679 
ostrstream() destructor 680 
out open_mode flag 652 
out_waiting() function 695 
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output stream 623 
ovlyMgr function 370 


p 

padding flags, enum format-state (class ios) 646 
parentheses ( ) 

using with complex extraction and insertion operators 
618 

parms=both compiler option 33, 34 
parms= register compiler option 
defining user-written functions 33, 34 
definition 14 

using registerized parameters 3 
pcount() function 
class ostrstream 680 
class strstream 685 
peek() function 662 
perror function 371 
polar() function 609 
poserr function 372 
pound signs (##) 

beginning instructions in .fd files 40 
pow function 375 
pow() function 610-611 
pow2 function 376 
#pragma amicall statement 
format 36 
purpose 34 

#pragma flibcall statement 
calculating magic value 38, 39 
format 36 
purpose 34 

#pragma libcall statement 
accessing functions in exec.library 7 
calculating magic value 38, 39 
format 35 
purpose 34 

fpragma msg statement 35 
fpragma regcall statement 
format 37 
purpose 35 

fpragma statements 34-42 
accessing functions in exec.library 7 
accessing shared libraries 6-7 
advantages 6, 34 
calculating magic value 38-40 
creating function description (.fd) file 40-41 
creating user-defined #pragma statements 34-37, 48 
generating with fd2pragma utility 40-42 


header files 24 

types of #pragma statements 34-35 
fpragma syscall statement 
accessing functions in exec.library 7 
calculating magic value 38, 39 
format 37 
purpose 34 

#pragma tagcall statement 

calculating magic value 38, 39 
format 37 
purpose 35 
precision() function 
class ios 642 
purpose 627 
precompiled header files 
difference from global symbol tables (GSTs) 29 
predefined data names 
—BackGroundIO 62 
—Backstdout 63 
DOSBase 68 
errno 69-71 
—FPERR 74-75 
GfxBase 76 
IntuitionBase 77 
MathBase 78 
MathTranBase 79 
—MemType 80-81 
—msflag 86 
_MSTEP 87 
_OSERR 91-94 
_procname 96 
—stack 98 
SysBase 103 

buffsize 64 

ctype 65-66 

daytbl 67 

fmask 72 

fmode 73 

montbl 82-83 

months 84-85 

nufbs 88 

oslibversion 89-90 

priority 95 

sigfunc 97 

stdiov37 99-100 

stdiowin 101 

STKNEED 102 

sys_ errlist 104 

sys_ nerr 105 

_ TZ 106 



726 Index 


predefined data names (continued) 

ufbs 107 

—WBenchMsg 108 
predefined manipulators 
See class IOMANIP 
See manipulators 
prefix output functions 672-673 
prefs directory 25 
prefs subdirectory 25 
preprocessor symbols 

requirements for global symbol tables (GSTs) 31 
— STRICT — ANSI preprocessor symbol, defining 110 

USE— SYSBASE 7 

printf function 373-374 
description 373-374 
including prototype, example 22 
— priority data name 95 
##private instruction 
function description (.fd) file 41 
process ID structure 243 
—procname data name 96 
program control functions 
abort 131-132 
atexit 148 

autoopenfail 153 

Chk_ Abort 161-162 
chkabort 161-162 

CXBRK 179 

exit 209-210 
— exit 211 
forkl 241-244 
forkv 241-244 
longjmp 319 
onbreak 362-363 
onexit 364-365 
raise 386 
setjmp 416-417 
signal 424-425 
wait 598 
waitm 598 
—XCEXIT 602 
programs, compiling 
See also sc command 
custom libraries 44 
#pragma statements 6 

specifying correct library using compiler options 14-15 
stub routines 6 
programs, linking 
See also slink command 
automatic linking of libraries to programs 13 
custom libraries 44 


linking multiple libraries in correct order 15 
^pragma statements 6 

specifying correct library with compiler options 15-17 
stub routines 6 
-PROLOG function 377-378 
proto/all.h header file 7 
proto/exec.h header file 7 
prototype files 

See also #pragma statements 
accessing shared libraries 2, 6-7 
header files 24 
prototypes 

contained in new.h header file 605 
printf function prototype, example 22 
providing for all called functions 21-22 
required by C++ language 22 
using header files for including 22 
##public instruction 
function description (.fd) file 40 
put pointer 

moving with seekoff() function 692, 697, 702 
moving with seekpos() function 689, 693, 702 
purpose and use 626 
setting with seekoff() function 688 
setting with seekpos() function 698 
synchronizing with sync() function 693, 696 
put() function 676 
putback() function 
class istream 662 
purpose and use 625 
putc function 379 
putchar function 380 
putenv function 381-382 
putreg function 383 
puts function 384 
pword() function 643 


Q 

qsort function 385 


R 

raise function 386 
rand function 387-388 
random-number generation functions 
drand48 197 
erand48 206 
jrand48 308 
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lcong48 310 
lrand48 321 
mrand48 358 
nrand48 359 
rand 387-388 
seed48 413 
srand 433 
srand48 434 
rawcon function 389-390 
rbrk function 391 
rdbuf() function 
class ios 641 
class istrstream 665 
class ostrstream 680 
class stdiostream 681 
class strstream 685 
rdstate() function 651 
read function 392 
READ mode, fopen function 236 
read() function 
class istream 662 
purpose and use 625 
readdir function 393 
readlocale function 394 
real() function 609 
realloc function 395 

regargs keyword 33, 34 

regcall #pragma statement 
format 37 
purpose 35 
register keyword 46 
registerized parameters 3, 33 
registers 
AO 54 
A1 54, 55 
A4 50 
A6 6, 38, 50 
A7 38 
DO 54, 55 

hexadecimal numbers for #pragma statements 38 
requirements for shared libraries 5 
restrictions for C + + shared libraries 53-54 
separating in .fd file 41 
remove function 396-397 
rename function 398-399 
repmem function 400-401 
resetiosflags() manipulator 707 
RESLEN global symbol 52 
.resource files 
library bases 11 
rules for initializing libraries 8 


resources subdirectory 25 

revision numbers for library bases 8, 89 

rewind function 402 

rewinddir function 403 

rexx subdirectory 25 

right padding (leading padding) 674 

right padding flag 646 

rlsmem function 404 

rlsml function 405 

rmdir function 406 

rstmem function 407 


s 

SAS/C libraries 
See linkable libraries 

saveds keyword 46, 50 

sbrk function 408 
sbumpc() function 695 
sc command 

See also compiler options 

See also programs, compiling 

automatic linking of libraries to programs 13 

choice of options for linking with libraries 16-17 

compiler's role in creating shared libraries 50 

creating custom shared libraries 47-48 

link option 15 

linking programs with libraries, examples 16 
specifying custom linkable libraries 44 
sc.lib 2 

scanf function 409 

scdir function 410 

scientific floating-point flag 647, 675 

scm.lib 2, 18 

scmffp.lib 3, 18 

scmieee.lib 3, 18 

scmnb.lib 3, 19 

scms.lib 3, 18 

scm881.1ib 3, 19 

scnb.lib 3 

scompact command 28 

screen control (scr ) functions 411-412 

scs.lib 3 
scsnb.lib 3 

search path for include files 25—26 
seed48 function 413 
seek_dir flags 654 
seekdir function 414 
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seekg() function 
class istream 663 
purpose and use 626 
seekoff() function 
See also fseek function 
class filebuf 688-689 
class stdiobuf 692 
class streambuf 697 
class strstreambuf 702 
seekp() function 
class ostream 677 
purpose and use 626 
seekpos() function 
See also fsetpos function 
class filebuf 689 
class stdiobuf 693 
class streambuf 698 
class strstreambuf 702 
set_new_handler() function 605 
setbuf function 415 
setbuf() function 
class filebuf 689 
class strstreambuf 702 
setf() function 648, 649 
setfill() manipulator 706 
setiosflags() manipulator 706 
setjmp function 

avoiding in C + + programs 603 
avoiding in custom shared libraries 45 
syntax and description 416-417 
setlocale function 418-419 
setmem function 420 
setnbf function 421 
setprecision() manipulator 706 
setvbuf function 422-423 
setw() manipulator 706 
sget() function 695 
sgetn() function 695 
shared C++ libraries, creating 53-59 
creating .fd file 54-55 
declaring C+ + functions in library 53-54 
example 56-57 

initialization and termination 57-59 
register restrictions 53-54 
shared libraries 1-2, 5-11 
access methods 2, 5 
amiga.lib 5-6 
compared with devices 59 

correlation between header file directories and library 
directories 24 
defining library bases 7-11 


definition 1 
header files 23-25 

#pragma statements for accessing 6-7 
stub routines for accessing 5-6 
shared libraries, creating 44-53 
avoiding non-reentrant functions 44 
calling functions 49 
compiler’s role 50 
format of shared libraries 52-53 
LibClose function 51 
LibExpunge function 51 
Liblnit function 50 
LibOpen function 51 
library that copies near data section 45 
linker’s role 52 

naming with .library extension 42 
one near data section 44 
restrictions 45 
steps for creating 46-48 
when to create 42 
shortint compiler option 14, 17 
showbase format flag 647, 675 
showpoint format flag 647, 676 
showpos format flag 647, 675, 676 
— sigfunc data name 97 
signal function 424-425 
sin function 426 
sin() function 612-614 
sinh function 427 
sinh() function 612-614 
sizmem function 428 
skipws flag 646 
slash (/) 

separating registers in .fd file 41 
slink command 
See also programs, linking 
global symbols defined by 52 
linker’s role in creating shared libraries 52 
linking multiple libraries in correct order 15 
specifying correct library 13, 15 
snextc() function 695 
sorting functions 
bsearch 155 
dqsort 1 96 
fqsort 258 
lqsort 320 
qsort 385 
sqsort 431 
strsrt 545-546 
tqsort 576 

sprintf function 429-430 



sputbackc() function 696 
sputc() function 696 
sputn() function 696 
sqrt function 432 
sqrt() function 610-611 
sqsort function 431 
srand function 433 
srand48 function 434 
sscanf function 435 

stack data name 98 

stackavail function 436 

stackext keyword 47 

stackextend compiler option 47 
stacksize function 437 
stackused function 438 
standard I/O functions 
fgetchar 223 
fputchar 256 
getch 280 
getchar 281 
gets 298-299 
printf 373-374 
putchar 380 
puts 384 
scanf 409 
vprintf 594-595 
standard I/O window 

See stdiov37 data name 

See stdiowin data name 

stat function 439-440 
stat structure 270, 325, 439 
state flags 628 

static mode, class strstreambuf 700 

status of I/O stream 628 

stcarg function 441-442 

stccpy function 443 

stcd_i function 444-445 

stcd_l function 446-447 

stcgfe function 448-449 

stcgfn function 450 

stcgfp function 451-452 

stch_i function 453-454 

stch_l function 455-456 

stci_d function 457-458 

stci_h function 459-460 

stci_o function 461-462 

stcis function 463-464 

stcisn function 465-466 

stcL_d function 467-468 

stcL_h function 469-470 

stcl —0 function 471-472 


stclen function 473 
stco_i function 474-475 
stco_l function 476-477 
stcpm function 
example 383-384 
pattern-matching characters 478 
portability 383 
returns 383 

syntax and description 478-479 
stcpma function 
example 482-483 
pattern-matching characters 481 
portability 482 
returns 482 

syntax and description 481-482 
stcsma function 484 
stcu_d function 485-486 
stcul_d function 487-488 
stdio format flag 648 
stdiobuf class 
See class stdiobuf 
stdiobuf() constructor 692 
stdiobuf() destructor 692 
stdiofile() function 681 
stdiostream() constructor 681 

stdiov37 data name 99-100 

stdiowin data name 101 

STKNEED data name 102 

stossc() function 695 
stpblk function 489 
stpbrk function 490 
stpchr function 491 
stpchrn function 492 
stpcpy function 493 
stpdate function 494-495 
stpsym function 496-497 
stptime function 498-499 
stptok function 500-501 
str() function 
class ostrstream 680 
class strstream 685 
class strstreambuf 701 
strbpl function 502-503 
strcat function 504 
strchr function 505 
strcmp function 506-508 
strcmpi function 509 
strcoll function 510 
strcpy function 511 
strcspn function 512 
strdup function 513 
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stream classes 631-685 
class fstream 632-635 
class ifstream 636-639 
class ios 640-644 
class iostream 655 
class istream 656-663 
class istrstream 664-666 
class ofstream 667-670 
class ostream 671-678 
class ostrstream 679-680 
class stdiostream 681 
class streampos 682-683 
class strstream 684-685 
enum format-state, class ios 645-649 
enum io_state, class ios 650-651 
enum open_mode, class ios 652-653 
enum seek_dir, class ios 654 
stream.h header file 629-630 
streambuf class 
See class streambuf 
streampos() constructor 682 
streams 

See also stream classes 
class hierarchy 620-623 

compatibility of SAS/C C+ + library with AT&T Release 
2 620, 629-630 
creating 623 
definition 620 

determining status of I/O streams (state flags) 628 
formatting C+ + I/O 627-628 

frequently used stream class member functions 625-626 
get pointer 626 
naming conventions 622 
purpose 620 
put pointer 626 
strerror function 514 
strftime function 515-517 
stricmp function 518-519 

— STRICT — ANSI preprocessor symbol, defining 110 
string functions 
astcsma 144-145 
scdir 410 
stcarg 441-442 
stccpy 443 
stcis 463-464 
stcisn 465-466 
stclen 473 
stcpm 478-480 
stcpma 481-483 
stcsma 484 
stpblk 489 


stpbrk 490 
stpchr 491 
stpchm 492 
stpcpy 493 
stpsym 496-497 
stptok 500-501 
strbpl 502-503 
strcat 504 
strchr 505 
strcmp 506-508 
strcmpi 509 
strcpy 511 
strcspn 512 
strdup 513 
stricmp 518-519 
strins 520 
strlen 521 
strmid 527 
strncat 528-529 
strncmp 530-531 
strncpy 532 
strnicmp 533-534 
strnset 535 
strpbrk 536 
strrchr 537-538 
strrev 539 
strset 540 
strspn 543-544 
strstr 547 
strtok 550-551 
string I/O functions 
fgets 227-228 
fputs 257 
gets 298-299 
puts 384 
strins function 520 
strlen function 521 
strlwr function 522 
strmfe function 523 
strmfn function 524-525 
strmfp function 526 
strmid function 527 
strncat function 528-529 
strncmp function 530-531 
strncpy function 532 
strnicmp function 533-534 
strnset function 535 
strpbrk function 536 
strrchr function 537-538 
strrev function 539 
strset function 540 



strsfn function 541-542 
strspn function 543-544 
strsrt function 545-546 
strstr function 547 
strstream() constructor 684 
strstream() destructor 685 
strstreambuf class 
See class strstreambuf 
strstreambuf() constructor 700-701 
strstreambuf() destructor 701 
strtod function 548-549 
strtok function 550-551 
strtol function 552-553 
strtoul function 554-555 
structures 

FORKENV structure 242 
process ID structure 243 
stat 270, 325, 439 
TermMsg structure 242-243 
tm 353-354 
strupr function 556 
strxfrm function 557-558 
stspfp function 559 
_stub function 560 
stub routines 

accessing shared libraries 1, 5-6 
purpose 5 

suffix output functions 672-673 
swmem function 561 
symbols 

See also global symbols 
See also preprocessor symbols 
LinkerDB 50 

LibFuncTab 52 

Libmergeddata 50 

sync() function 
class filebuf 689 
class istream 662 
class stdiobuf 693 
class streambuf 696 

sys_errlist data name 104 

sys_nerr data name 105 

SysBase data name 103 
SysBase variable 7 
syscall #pragma statement 
accessing functions in exec.library 7 
calculating magic value 38, 39 
format 37 
purpose 34 
system function 562 


system header files 
See header files 
system interface functions 
argopt 137-139 
chgclk 160 
dos—packet 195 
getasn 276-277 
getclk 282 
getdfs 284-285 
getenv 286-287 
putenv 381-382 
rawcon 389-390 
stackavail 436 
stacksize 437 
stackused 438 
system 562 


T 

tagcall #pragma statement 
calculating magic value 38, 39 
format 37 
purpose 35 
tan function 563 
tanh function 564 
tell function 565 
telldir function 566 
tellg() function 
class istream 663 
purpose and use 626 
tellp() function 
class ostream 677 
purpose and use 626 
TermMsg structure 242-243 
tie() function 
class ios 641 
purpose and use 625 
time function 567 
time functions 
asctime 140 
clock 168-169 
dime 177-178 
datecmp 182 
difftime 188-189 
gmtime 300-301 
local time 316 
mktime 353-354 
strftime 515-517 
time 567 
timer 569 
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time functions ( continued ) 
utpack 583-584 
utunpk 585-586 

timecvt 568 

tzset 577-578 

— timecvt function 568 

— tinymain function 570 

timer function 569 

tm structure 353-354 

tmpfile function 571-572 

tmpnam function 573 

toascii function 574-575 

tolower function 574-575 

toupper function 574-575 

tqsort function 576 

trailing padding 674 

TRANSLATE mode, fopen function 237 

TRUNC mode, fopen function 236 

trunc open_mode flag 652-653 

_TZ data name 106 

— tzset function 577-578 


u 

— ufbs data name 107 

unformatted input functions, class istream 661-662 
ungetc function 579-580 
unitbuf format flag 648 
UNIX-compatible functions 23 
unlink function 581-582 
unsetfQ function 648 
uppercase format flag 647, 676 
— USE — SYSBASE preprocessor symbol 7 
user-defined format flag functions 642-643 
user-defined functions 33-34 
user-defined libraries 
See linkable libraries, creating 
See shared libraries, creating 
user-defined manipulators 707-710 
— UserLibCleanup function 47 
— UserLiblnit function 46, 47, 50 
— UserLibTerm function 51 
utility macros and functions 
See general utility macros and functions 
utpack function 583-584 
utunpk function 585-586 


v 

va__arg function 587-589 
va_end function 590 
va_start function 591 
version number for libraries 49 
vfprintf function 592-593 
void* operator 

converting ios object to pointer 651 

testing streams for errors 628 
vprintf function 594-595 
vsprintf function 596-597 


w 

wait function 598 
waitm function 598 
—WBenchMsg data name 108 
wcstombs function 599 
wctomb function 600 
width() function 
class ios 642 
class ostream 673, 674 
purpose 627 
with files 

displaying contents 6 
linking custom libraries 44 
specifying libraries with compiler options 6 
write function 601 
WRITE mode, fopen function 237 
write() function 
class ostream 677 
purpose and use 625 
ws manipulator 
class ios 643 
formatting C + + I/O 627 

x 

xalloc() function 643 
—XCEXIT function 602 

Special Characters 

= = operator 
See complex operators 
/ (division) operator 
See complex operators 
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/ (slash) 

See slash (/) 

/= operator 
See complex operators 
<< operator 

See insertion << operator 
( ) (parentheses) 

See parentheses ( ) 

+ (Addition) operator 
See complex operators 
+ = operator 
See complex operators 
! (exclamation point) 

See exclamation point (!) operator 
!= operator 
See complex operators 

* (asterisk) 

See asterisk (*) 

* (multiplication) operator 
See complex operators 

*= operator 
See complex operators 
- (negation) operator 
See complex operators 
-= operator 
See complex operators 
>> operator 

See extraction >> operator 
## (pound signs) 

See pound signs (##) 
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